ebk 0.4.4__py3-none-any.whl

ebk/library_db.py

@@ -0,0 +1,1440 @@
+"""
+Database-backed Library class for ebk.
+
+Provides a fluent API for managing ebook libraries using SQLAlchemy + SQLite.
+"""
+
+from pathlib import Path
+from typing import List, Dict, Any, Optional, Tuple
+from datetime import datetime
+import logging
+
+from sqlalchemy import func, or_, and_, text, update
+from sqlalchemy.orm import Session
+
+from .db.models import Book, Author, Subject, File, PersonalMetadata
+from .db.session import init_db, get_session, close_db
+from .services.import_service import ImportService
+from .services.text_extraction import TextExtractionService
+from .search_parser import parse_search_query
+
+logger = logging.getLogger(__name__)
+
+
+class Library:
+    """
+    Database-backed library for managing ebooks.
+
+    Usage:
+        lib = Library.open("/path/to/library")
+        lib.add_book(Path("book.pdf"), {"title": "My Book", "creators": ["Author"]})
+        results = lib.search("python programming")
+        stats = lib.stats()
+        lib.close()
+    """
+
+    def __init__(self, library_path: Path, session: Session):
+        self.library_path = Path(library_path)
+        self.session = session
+        self.import_service = ImportService(library_path, session)
+        self.text_service = TextExtractionService(library_path)
+
+    @classmethod
+    def open(cls, library_path: Path, echo: bool = False) -> 'Library':
+        """
+        Open or create a library.
+
+        Args:
+            library_path: Path to library directory
+            echo: If True, log all SQL statements
+
+        Returns:
+            Library instance
+        """
+        library_path = Path(library_path)
+        init_db(library_path, echo=echo)
+        session = get_session()
+
+        logger.debug(f"Opened library at {library_path}")
+        return cls(library_path, session)
+
+    def close(self):
+        """Close library and cleanup database connection."""
+        if self.session:
+            self.session.close()
+        close_db()
+        logger.debug("Closed library")
+
+    def add_book(self, file_path: Path, metadata: Dict[str, Any],
+                 extract_text: bool = True, extract_cover: bool = True) -> Optional[Book]:
+        """
+        Add a book to the library.
+
+        Args:
+            file_path: Path to ebook file
+            metadata: Metadata dictionary (title, creators, subjects, etc.)
+            extract_text: Whether to extract full text
+            extract_cover: Whether to extract cover image
+
+        Returns:
+            Book instance or None if import failed
+        """
+        book = self.import_service.import_file(
+            file_path,
+            metadata,
+            extract_text=extract_text,
+            extract_cover=extract_cover
+        )
+
+        if book:
+            logger.debug(f"Added book: {book.title}")
+
+        return book
+
+    def add_calibre_book(self, metadata_opf_path: Path) -> Optional[Book]:
+        """
+        Add book from Calibre metadata.opf file.
+
+        Args:
+            metadata_opf_path: Path to metadata.opf
+
+        Returns:
+            Book instance or None
+        """
+        return self.import_service.import_calibre_book(metadata_opf_path)
+
+    def batch_import(self, files_and_metadata: List[Tuple[Path, Dict[str, Any]]],
+                    show_progress: bool = True) -> List[Book]:
+        """
+        Import multiple books with progress tracking.
+
+        Args:
+            files_and_metadata: List of (file_path, metadata) tuples
+            show_progress: Whether to show progress bar
+
+        Returns:
+            List of imported Book instances
+        """
+        file_paths = [f for f, _ in files_and_metadata]
+        metadata_list = [m for _, m in files_and_metadata]
+
+        return self.import_service.batch_import(
+            file_paths,
+            metadata_list,
+            show_progress=show_progress
+        )
+
+    def get_book(self, book_id: int) -> Optional[Book]:
+        """Get book by ID."""
+        return self.session.get(Book, book_id)
+
+    def get_book_by_unique_id(self, unique_id: str) -> Optional[Book]:
+        """Get book by unique ID."""
+        return self.session.query(Book).filter_by(unique_id=unique_id).first()
+
+    def query(self) -> 'QueryBuilder':
+        """Start a fluent query."""
+        return QueryBuilder(self.session)
+
+    def search(self, query: str, limit: int = 50, offset: int = 0) -> List[Book]:
+        """
+        Advanced search across books with field-specific queries and boolean logic.
+
+        Supports:
+            - Field searches: title:Python, author:Knuth, tag:programming
+            - Phrases: "machine learning"
+            - Boolean: AND (implicit), OR (explicit), NOT/-prefix (negation)
+            - Comparisons: rating:>=4, rating:3-5
+            - Filters: language:en, format:pdf, favorite:true
+
+        Examples:
+            title:Python rating:>=4 format:pdf
+            author:"Donald Knuth" series:TAOCP
+            tag:programming favorite:true NOT java
+
+        Args:
+            query: Search query (supports advanced syntax or plain text)
+            limit: Maximum number of results
+            offset: Number of results to skip (for pagination)
+
+        Returns:
+            List of matching books
+        """
+        try:
+            # Parse the query
+            parsed = parse_search_query(query)
+
+            # If no FTS terms and no filters, return empty
+            if not parsed.has_fts_terms() and not parsed.has_filters():
+                return []
+
+            # Build the query
+            book_ids = []
+
+            # If we have FTS terms, search FTS5 first
+            if parsed.has_fts_terms():
+                result = self.session.execute(
+                    text("""
+                    SELECT book_id, rank
+                    FROM books_fts
+                    WHERE books_fts MATCH :query
+                    ORDER BY rank
+                    LIMIT :limit OFFSET :offset
+                    """),
+                    {"query": parsed.fts_query, "limit": limit + offset + limit, "offset": 0}  # Get more for filtering
+                )
+                book_ids = [row[0] for row in result]
+
+                if not book_ids:
+                    return []
+
+            # Build filter conditions
+            from .search_parser import SearchQueryParser
+            parser = SearchQueryParser()
+            where_clause, params = parser.to_sql_conditions(parsed)
+
+            # If we have both FTS and filters, combine them
+            if book_ids and where_clause:
+                # Start with FTS results and apply filters
+                books_query = self.session.query(Book).filter(
+                    Book.id.in_(book_ids)
+                )
+
+                # Apply additional SQL filters
+                books_query = books_query.filter(text(where_clause).bindparams(**params))
+
+                books = books_query.all()
+
+                # Maintain FTS ranking order and apply offset/limit
+                books_dict = {b.id: b for b in books}
+                ordered = [books_dict[bid] for bid in book_ids if bid in books_dict]
+                return ordered[offset:offset + limit]
+
+            # If only FTS (no additional filters)
+            elif book_ids:
+                books = self.session.query(Book).filter(Book.id.in_(book_ids)).all()
+                books_dict = {b.id: b for b in books}
+                ordered = [books_dict[bid] for bid in book_ids if bid in books_dict]
+                return ordered[offset:offset + limit]
+
+            # If only filters (no FTS)
+            elif where_clause:
+                books_query = self.session.query(Book)
+                books_query = books_query.filter(text(where_clause).bindparams(**params))
+                return books_query.offset(offset).limit(limit).all()
+
+            return []
+
+        except Exception as e:
+            logger.error(f"Search error: {e}")
+            logger.exception(e)
+            # Fallback to original simple FTS search
+            try:
+                result = self.session.execute(
+                    text("""
+                    SELECT book_id, rank
+                    FROM books_fts
+                    WHERE books_fts MATCH :query
+                    ORDER BY rank
+                    LIMIT :limit
+                    """),
+                    {"query": query, "limit": limit}
+                )
+                book_ids = [row[0] for row in result]
+                if not book_ids:
+                    return []
+                books = self.session.query(Book).filter(Book.id.in_(book_ids)).all()
+                books_dict = {b.id: b for b in books}
+                return [books_dict[bid] for bid in book_ids if bid in books_dict]
+            except Exception as fallback_error:
+                logger.error(f"Fallback search also failed: {fallback_error}")
+                return []
+
+    def stats(self) -> Dict[str, Any]:
+        """
+        Get library statistics.
+
+        Returns:
+            Dictionary with statistics
+        """
+        total_books = self.session.query(func.count(Book.id)).scalar()
+        total_authors = self.session.query(func.count(Author.id)).scalar()
+        total_subjects = self.session.query(func.count(Subject.id)).scalar()
+        total_files = self.session.query(func.count(File.id)).scalar()
+
+        # Reading stats
+        read_count = self.session.query(func.count(PersonalMetadata.id)).filter(
+            PersonalMetadata.reading_status == 'read'
+        ).scalar()
+
+        reading_count = self.session.query(func.count(PersonalMetadata.id)).filter(
+            PersonalMetadata.reading_status == 'reading'
+        ).scalar()
+
+        # Language distribution
+        lang_dist = self.session.query(
+            Book.language,
+            func.count(Book.id)
+        ).group_by(Book.language).all()
+
+        # Format distribution
+        format_dist = self.session.query(
+            File.format,
+            func.count(File.id)
+        ).group_by(File.format).all()
+
+        return {
+            'total_books': total_books,
+            'total_authors': total_authors,
+            'total_subjects': total_subjects,
+            'total_files': total_files,
+            'read_count': read_count,
+            'reading_count': reading_count,
+            'languages': dict(lang_dist),
+            'formats': dict(format_dist)
+        }
+
+    def get_all_books(self, limit: Optional[int] = None, offset: int = 0) -> List[Book]:
+        """
+        Get all books with optional pagination.
+
+        Args:
+            limit: Maximum number of books
+            offset: Starting offset
+
+        Returns:
+            List of books
+        """
+        query = self.session.query(Book).order_by(Book.title)
+
+        if limit:
+            query = query.limit(limit).offset(offset)
+
+        return query.all()
+
+    def get_books_by_author(self, author_name: str) -> List[Book]:
+        """Get all books by an author."""
+        return self.session.query(Book).join(Book.authors).filter(
+            Author.name.ilike(f"%{author_name}%")
+        ).all()
+
+    def get_books_by_subject(self, subject_name: str) -> List[Book]:
+        """Get all books with a subject."""
+        return self.session.query(Book).join(Book.subjects).filter(
+            Subject.name.ilike(f"%{subject_name}%")
+        ).all()
+
+    def update_reading_status(self, book_id: int, status: str,
+                             progress: Optional[int] = None,
+                             rating: Optional[int] = None):
+        """
+        Update reading status for a book.
+
+        Args:
+            book_id: Book ID
+            status: Reading status (unread, reading, read)
+            progress: Reading progress percentage (0-100)
+            rating: Rating (1-5)
+        """
+        personal = self.session.query(PersonalMetadata).filter_by(
+            book_id=book_id
+        ).first()
+
+        if personal:
+            personal.reading_status = status
+            if progress is not None:
+                personal.reading_progress = progress
+            if rating is not None:
+                personal.rating = rating
+
+            if status == 'read':
+                personal.date_finished = datetime.now()
+
+            self.session.commit()
+            logger.debug(f"Updated reading status for book {book_id}: {status}")
+
+    def set_favorite(self, book_id: int, favorite: bool = True):
+        """
+        Mark/unmark book as favorite.
+
+        Args:
+            book_id: Book ID
+            favorite: True to mark as favorite, False to unmark
+        """
+
+
+        personal = self.session.query(PersonalMetadata).filter_by(
+            book_id=book_id
+        ).first()
+
+        if not personal:
+            # Create personal metadata if it doesn't exist
+            personal = PersonalMetadata(book_id=book_id, favorite=favorite)
+            self.session.add(personal)
+        else:
+            personal.favorite = favorite
+
+        self.session.commit()
+        logger.debug(f"Set favorite for book {book_id}: {favorite}")
+
+    # Reading Queue Methods
+
+    def get_reading_queue(self) -> List[Book]:
+        """
+        Get all books in the reading queue, ordered by position.
+
+        Returns:
+            List of books in queue order
+        """
+
+
+        return self.session.query(Book).join(Book.personal).filter(
+            PersonalMetadata.queue_position.isnot(None)
+        ).order_by(PersonalMetadata.queue_position).all()
+
+    def add_to_queue(self, book_id: int, position: Optional[int] = None):
+        """
+        Add a book to the reading queue.
+
+        Args:
+            book_id: Book ID to add
+            position: Position in queue (1-based). If None, adds to end.
+        """
+
+
+        personal = self.session.query(PersonalMetadata).filter_by(
+            book_id=book_id
+        ).first()
+
+        if not personal:
+            personal = PersonalMetadata(book_id=book_id)
+            self.session.add(personal)
+            self.session.flush()
+
+        # Get current max position
+        max_pos = self.session.query(func.max(PersonalMetadata.queue_position)).scalar() or 0
+
+        if position is None:
+            # Add to end
+            personal.queue_position = max_pos + 1
+        else:
+            # Insert at specific position, shift others down
+            position = max(1, position)  # Ensure positive
+            self.session.query(PersonalMetadata).filter(
+                PersonalMetadata.queue_position >= position,
+                PersonalMetadata.queue_position.isnot(None)
+            ).update({PersonalMetadata.queue_position: PersonalMetadata.queue_position + 1})
+            personal.queue_position = position
+
+        self.session.commit()
+        logger.debug(f"Added book {book_id} to queue at position {personal.queue_position}")
+
+    def remove_from_queue(self, book_id: int):
+        """
+        Remove a book from the reading queue.
+
+        Args:
+            book_id: Book ID to remove
+        """
+
+
+        personal = self.session.query(PersonalMetadata).filter_by(
+            book_id=book_id
+        ).first()
+
+        if personal and personal.queue_position is not None:
+            old_position = personal.queue_position
+            personal.queue_position = None
+
+            # Shift other items up to fill gap
+            self.session.query(PersonalMetadata).filter(
+                PersonalMetadata.queue_position > old_position
+            ).update({PersonalMetadata.queue_position: PersonalMetadata.queue_position - 1})
+
+            self.session.commit()
+            logger.debug(f"Removed book {book_id} from queue")
+
+    def reorder_queue(self, book_id: int, new_position: int):
+        """
+        Move a book to a new position in the queue.
+
+        Args:
+            book_id: Book ID to move
+            new_position: New position (1-based)
+        """
+
+
+        personal = self.session.query(PersonalMetadata).filter_by(
+            book_id=book_id
+        ).first()
+
+        if not personal or personal.queue_position is None:
+            # Not in queue, add it
+            self.add_to_queue(book_id, new_position)
+            return
+
+        old_position = personal.queue_position
+        new_position = max(1, new_position)
+
+        if old_position == new_position:
+            return  # No change needed
+
+        if old_position < new_position:
+            # Moving down: shift items between old and new up
+            self.session.query(PersonalMetadata).filter(
+                PersonalMetadata.queue_position > old_position,
+                PersonalMetadata.queue_position <= new_position,
+                PersonalMetadata.queue_position.isnot(None)
+            ).update({PersonalMetadata.queue_position: PersonalMetadata.queue_position - 1})
+        else:
+            # Moving up: shift items between new and old down
+            self.session.query(PersonalMetadata).filter(
+                PersonalMetadata.queue_position >= new_position,
+                PersonalMetadata.queue_position < old_position,
+                PersonalMetadata.queue_position.isnot(None)
+            ).update({PersonalMetadata.queue_position: PersonalMetadata.queue_position + 1})
+
+        personal.queue_position = new_position
+        self.session.commit()
+        logger.debug(f"Moved book {book_id} from position {old_position} to {new_position}")
+
+    def clear_queue(self):
+        """Clear all books from the reading queue."""
+
+
+        self.session.query(PersonalMetadata).filter(
+            PersonalMetadata.queue_position.isnot(None)
+        ).update({PersonalMetadata.queue_position: None})
+        self.session.commit()
+        logger.debug("Cleared reading queue")
+
+    def add_tags(self, book_id: int, tags: List[str]):
+        """
+        Add personal tags to a book.
+
+        Args:
+            book_id: Book ID
+            tags: List of tag strings
+        """
+
+
+        personal = self.session.query(PersonalMetadata).filter_by(
+            book_id=book_id
+        ).first()
+
+        if not personal:
+            personal = PersonalMetadata(book_id=book_id, personal_tags=tags)
+            self.session.add(personal)
+        else:
+            existing_tags = personal.personal_tags or []
+            # Add new tags without duplicates
+            combined = list(set(existing_tags + tags))
+            personal.personal_tags = combined
+
+        self.session.commit()
+        logger.debug(f"Added tags to book {book_id}: {tags}")
+
+    def remove_tags(self, book_id: int, tags: List[str]):
+        """
+        Remove personal tags from a book.
+
+        Args:
+            book_id: Book ID
+            tags: List of tag strings to remove
+        """
+
+
+        personal = self.session.query(PersonalMetadata).filter_by(
+            book_id=book_id
+        ).first()
+
+        if personal and personal.personal_tags:
+            personal.personal_tags = [t for t in personal.personal_tags if t not in tags]
+            self.session.commit()
+            logger.debug(f"Removed tags from book {book_id}: {tags}")
+
+    def add_subject(self, book_id: int, subject_name: str):
+        """
+        Add a subject/tag to a book.
+
+        Args:
+            book_id: Book ID
+            subject_name: Subject/tag name to add
+        """
+        book = self.session.query(Book).filter_by(id=book_id).first()
+        if not book:
+            logger.warning(f"Book {book_id} not found")
+            return
+
+        # Check if subject already exists
+        subject = self.session.query(Subject).filter_by(name=subject_name).first()
+        if not subject:
+            subject = Subject(name=subject_name)
+            self.session.add(subject)
+
+        # Add subject to book if not already present
+        if subject not in book.subjects:
+            book.subjects.append(subject)
+            self.session.commit()
+            logger.debug(f"Added subject '{subject_name}' to book {book_id}")
+
+    def add_annotation(self, book_id: int, content: str,
+                      page: Optional[int] = None,
+                      annotation_type: str = 'note'):
+        """
+        Add an annotation/comment to a book.
+
+        Args:
+            book_id: Book ID
+            content: Annotation text
+            page: Page number (optional)
+            annotation_type: Type of annotation (note, highlight, bookmark)
+
+        Returns:
+            Annotation ID
+        """
+        from .db.models import Annotation
+
+        annotation = Annotation(
+            book_id=book_id,
+            content=content,
+            page_number=page,
+            annotation_type=annotation_type,
+            created_at=datetime.now()
+        )
+        self.session.add(annotation)
+        self.session.commit()
+
+        logger.debug(f"Added annotation to book {book_id}")
+        return annotation.id
+
+    def get_annotations(self, book_id: int) -> List:
+        """
+        Get all annotations for a book.
+
+        Args:
+            book_id: Book ID
+
+        Returns:
+            List of Annotation objects
+        """
+        from .db.models import Annotation
+
+        return self.session.query(Annotation).filter_by(
+            book_id=book_id
+        ).order_by(Annotation.created_at.desc()).all()
+
+    def delete_annotation(self, annotation_id: int):
+        """
+        Delete an annotation.
+
+        Args:
+            annotation_id: Annotation ID
+        """
+        from .db.models import Annotation
+
+        annotation = self.session.get(Annotation, annotation_id)
+        if annotation:
+            self.session.delete(annotation)
+            self.session.commit()
+            logger.debug(f"Deleted annotation {annotation_id}")
+
+    # -------------------------------------------------------------------------
+    # Review Methods
+    # -------------------------------------------------------------------------
+
+    def add_review(self, book_id: int, content: str,
+                   title: Optional[str] = None,
+                   rating: Optional[float] = None,
+                   review_type: str = 'personal',
+                   visibility: str = 'private') -> int:
+        """
+        Add a review to a book.
+
+        Args:
+            book_id: Book ID
+            content: Review text (markdown supported)
+            title: Review headline/title (optional)
+            rating: Rating 1-5 stars (optional, separate from book rating)
+            review_type: Type of review (personal, summary, critique, notes)
+            visibility: Visibility level (private, public)
+
+        Returns:
+            Review ID
+        """
+        from .db.models import Review
+
+        review = Review(
+            book_id=book_id,
+            content=content,
+            title=title,
+            rating=rating,
+            review_type=review_type,
+            visibility=visibility
+        )
+        self.session.add(review)
+        self.session.commit()
+
+        logger.debug(f"Added review to book {book_id}")
+        return review.id
+
+    def get_reviews(self, book_id: int) -> List:
+        """
+        Get all reviews for a book.
+
+        Args:
+            book_id: Book ID
+
+        Returns:
+            List of Review objects
+        """
+        from .db.models import Review
+
+        return self.session.query(Review).filter_by(
+            book_id=book_id
+        ).order_by(Review.created_at.desc()).all()
+
+    def get_review(self, review_id: int):
+        """
+        Get a specific review by ID.
+
+        Args:
+            review_id: Review ID
+
+        Returns:
+            Review object or None
+        """
+        from .db.models import Review
+        return self.session.get(Review, review_id)
+
+    def update_review(self, review_id: int,
+                      content: Optional[str] = None,
+                      title: Optional[str] = None,
+                      rating: Optional[float] = None,
+                      review_type: Optional[str] = None,
+                      visibility: Optional[str] = None) -> bool:
+        """
+        Update an existing review.
+
+        Args:
+            review_id: Review ID
+            content: New review text
+            title: New title
+            rating: New rating
+            review_type: New review type
+            visibility: New visibility
+
+        Returns:
+            True if updated, False if not found
+        """
+        from .db.models import Review
+
+        review = self.session.get(Review, review_id)
+        if not review:
+            return False
+
+        if content is not None:
+            review.content = content
+        if title is not None:
+            review.title = title
+        if rating is not None:
+            review.rating = rating
+        if review_type is not None:
+            review.review_type = review_type
+        if visibility is not None:
+            review.visibility = visibility
+
+        self.session.commit()
+        logger.debug(f"Updated review {review_id}")
+        return True
+
+    def delete_review(self, review_id: int) -> bool:
+        """
+        Delete a review.
+
+        Args:
+            review_id: Review ID
+
+        Returns:
+            True if deleted, False if not found
+        """
+        from .db.models import Review
+
+        review = self.session.get(Review, review_id)
+        if review:
+            self.session.delete(review)
+            self.session.commit()
+            logger.debug(f"Deleted review {review_id}")
+            return True
+        return False
+
+    def add_to_virtual_library(self, book_id: int, library_name: str):
+        """
+        Add a book to a virtual library (collection/view).
+
+        Args:
+            book_id: Book ID
+            library_name: Name of the virtual library
+        """
+
+
+        personal = self.session.query(PersonalMetadata).filter_by(
+            book_id=book_id
+        ).first()
+
+        if not personal:
+            # Use personal_tags as virtual_libraries array
+            personal = PersonalMetadata(book_id=book_id, personal_tags=[library_name])
+            self.session.add(personal)
+        else:
+            existing_libs = personal.personal_tags or []
+            if library_name not in existing_libs:
+                existing_libs.append(library_name)
+                personal.personal_tags = existing_libs
+
+        self.session.commit()
+        logger.debug(f"Added book {book_id} to virtual library '{library_name}'")
+
+    def remove_from_virtual_library(self, book_id: int, library_name: str):
+        """
+        Remove a book from a virtual library.
+
+        Args:
+            book_id: Book ID
+            library_name: Name of the virtual library
+        """
+
+
+        personal = self.session.query(PersonalMetadata).filter_by(
+            book_id=book_id
+        ).first()
+
+        if personal and personal.personal_tags:
+            personal.personal_tags = [lib for lib in personal.personal_tags if lib != library_name]
+            self.session.commit()
+            logger.debug(f"Removed book {book_id} from virtual library '{library_name}'")
+
+    def get_virtual_library(self, library_name: str) -> List[Book]:
+        """
+        Get all books in a virtual library.
+
+        Args:
+            library_name: Name of the virtual library
+
+        Returns:
+            List of books in this virtual library
+        """
+
+        # Query books where personal_tags contains the library_name
+        # This works with SQLite's JSON support
+        books = (self.session.query(Book)
+                .join(Book.personal)
+                .filter(PersonalMetadata.personal_tags.contains(library_name))
+                .all())
+
+        return books
+
+    def list_virtual_libraries(self) -> List[str]:
+        """
+        Get all unique virtual library names.
+
+        Returns:
+            List of virtual library names
+        """
+
+
+        # Get all personal_tags arrays and flatten them
+        all_metadata = self.session.query(PersonalMetadata).filter(
+            PersonalMetadata.personal_tags.isnot(None)
+        ).all()
+
+        libraries = set()
+        for pm in all_metadata:
+            if pm.personal_tags:
+                libraries.update(pm.personal_tags)
+
+        return sorted(list(libraries))
+
+    def delete_book(self, book_id: int, delete_files: bool = False):
+        """
+        Delete a book from the library.
+
+        Args:
+            book_id: Book ID
+            delete_files: If True, also delete physical files
+        """
+        book = self.get_book(book_id)
+        if not book:
+            logger.warning(f"Book {book_id} not found")
+            return
+
+        # Delete physical files if requested
+        if delete_files:
+            for file in book.files:
+                file_path = self.library_path / file.path
+                if file_path.exists():
+                    file_path.unlink()
+                    logger.debug(f"Deleted file: {file_path}")
+
+            # Delete covers
+            for cover in book.covers:
+                cover_path = self.library_path / cover.path
+                if cover_path.exists():
+                    cover_path.unlink()
+
+        # Delete from database (cascade will handle related records)
+        self.session.delete(book)
+        self.session.commit()
+        logger.debug(f"Deleted book: {book.title}")
+
+    def merge_books(
+        self,
+        primary_id: int,
+        secondary_ids: List[int],
+        delete_secondary_files: bool = False,
+    ) -> Tuple[Optional[Book], List[int]]:
+        """
+        Merge multiple books into one, combining metadata and files.
+
+        The primary book absorbs metadata and files from secondary books.
+        Secondary books are deleted after merging.
+
+        Merge strategy:
+        - Scalar fields: Keep primary's value, fallback to secondary if empty
+        - Relationships (authors, subjects, tags): Union of all
+        - Files/covers: Move all to primary
+        - Personal metadata: Keep higher rating, combine dates
+
+        Args:
+            primary_id: ID of the book to keep (receives merged data)
+            secondary_ids: IDs of books to merge into primary (will be deleted)
+            delete_secondary_files: If True, delete physical files from secondaries
+                                   that duplicate primary's files (by hash)
+
+        Returns:
+            Tuple of (merged book, list of deleted book IDs)
+
+        Example:
+            >>> merged, deleted = lib.merge_books(42, [43, 44])
+            >>> print(f"Merged {len(deleted)} books into {merged.title}")
+        """
+        from .db.models import (
+            Book, Author, Subject, Tag, File, Cover, Contributor,
+            Identifier, PersonalMetadata, BookConcept, ReadingSession,
+            Annotation, utc_now
+        )
+
+        # Get primary book
+        primary = self.get_book(primary_id)
+        if not primary:
+            logger.error(f"Primary book {primary_id} not found")
+            return None, []
+
+        # Get secondary books
+        secondaries = []
+        for sid in secondary_ids:
+            if sid == primary_id:
+                continue  # Skip if same as primary
+            book = self.get_book(sid)
+            if book:
+                secondaries.append(book)
+            else:
+                logger.warning(f"Secondary book {sid} not found, skipping")
+
+        if not secondaries:
+            logger.warning("No valid secondary books to merge")
+            return primary, []
+
+        deleted_ids = []
+
+        # Track existing file hashes to detect duplicates
+        primary_hashes = {f.file_hash for f in primary.files}
+
+        for secondary in secondaries:
+            logger.debug(f"Merging '{secondary.title}' into '{primary.title}'")
+
+            # === Merge scalar fields (prefer non-empty) ===
+            if not primary.subtitle and secondary.subtitle:
+                primary.subtitle = secondary.subtitle
+            if not primary.sort_title and secondary.sort_title:
+                primary.sort_title = secondary.sort_title
+            if not primary.language and secondary.language:
+                primary.language = secondary.language
+            if not primary.publisher and secondary.publisher:
+                primary.publisher = secondary.publisher
+            if not primary.publication_date and secondary.publication_date:
+                primary.publication_date = secondary.publication_date
+            if not primary.series and secondary.series:
+                primary.series = secondary.series
+            if primary.series_index is None and secondary.series_index is not None:
+                primary.series_index = secondary.series_index
+            if not primary.edition and secondary.edition:
+                primary.edition = secondary.edition
+            if not primary.rights and secondary.rights:
+                primary.rights = secondary.rights
+            if not primary.source and secondary.source:
+                primary.source = secondary.source
+            # For description, prefer longer one if both exist
+            if secondary.description:
+                if not primary.description or len(secondary.description) > len(primary.description):
+                    primary.description = secondary.description
+            if primary.page_count is None and secondary.page_count:
+                primary.page_count = secondary.page_count
+            if primary.word_count is None and secondary.word_count:
+                primary.word_count = secondary.word_count
+            # Merge keywords arrays
+            if secondary.keywords:
+                if primary.keywords:
+                    primary.keywords = list(set(primary.keywords + secondary.keywords))
+                else:
+                    primary.keywords = secondary.keywords
+            if not primary.color and secondary.color:
+                primary.color = secondary.color
+            # Keep earliest created_at
+            if secondary.created_at and (not primary.created_at or secondary.created_at < primary.created_at):
+                primary.created_at = secondary.created_at
+
+            # === Merge relationships (union) ===
+            # Authors
+            existing_author_ids = {a.id for a in primary.authors}
+            for author in secondary.authors:
+                if author.id not in existing_author_ids:
+                    primary.authors.append(author)
+
+            # Subjects
+            existing_subject_ids = {s.id for s in primary.subjects}
+            for subject in secondary.subjects:
+                if subject.id not in existing_subject_ids:
+                    primary.subjects.append(subject)
+
+            # Tags
+            existing_tag_ids = {t.id for t in primary.tags}
+            for tag in secondary.tags:
+                if tag.id not in existing_tag_ids:
+                    primary.tags.append(tag)
+
+            # Contributors - move to primary using SQL
+            from .db.models import Contributor as ContributorModel
+            for contrib in list(secondary.contributors):
+                self.session.execute(
+                    update(ContributorModel).where(ContributorModel.id == contrib.id).values(book_id=primary.id)
+                )
+
+            # Identifiers - move unique ones to primary using SQL
+            from .db.models import Identifier as IdentifierModel
+            existing_identifiers = {(i.scheme, i.value) for i in primary.identifiers}
+            for ident in list(secondary.identifiers):
+                if (ident.scheme, ident.value) not in existing_identifiers:
+                    self.session.execute(
+                        update(IdentifierModel).where(IdentifierModel.id == ident.id).values(book_id=primary.id)
+                    )
+
+            # Files - move to primary (handle duplicates by hash)
+            # Must use SQL UPDATE to bypass cascade delete on the relationship
+            from .db.models import File as FileModel
+
+            for file in list(secondary.files):
+                if file.file_hash in primary_hashes:
+                    # Duplicate file - explicitly delete
+                    if delete_secondary_files:
+                        file_path = self.library_path / file.path
+                        if file_path.exists():
+                            file_path.unlink()
+                            logger.debug(f"Deleted duplicate file: {file_path}")
+                    self.session.execute(
+                        update(FileModel).where(FileModel.id == file.id).values(book_id=None)
+                    )
+                    self.session.delete(file)
+                else:
+                    # Move file to primary using direct SQL to bypass cascade
+                    self.session.execute(
+                        update(FileModel).where(FileModel.id == file.id).values(book_id=primary.id)
+                    )
+                    primary_hashes.add(file.file_hash)
+
+            # Covers - move to primary using SQL to bypass cascade
+            from .db.models import Cover as CoverModel
+            for cover in list(secondary.covers):
+                self.session.execute(
+                    update(CoverModel).where(CoverModel.id == cover.id).values(
+                        book_id=primary.id,
+                        is_primary=False
+                    )
+                )
+
+            # Concepts - move to primary using SQL
+            from .db.models import BookConcept
+            for concept in list(secondary.concepts):
+                self.session.execute(
+                    update(BookConcept).where(BookConcept.id == concept.id).values(book_id=primary.id)
+                )
+
+            # Reading sessions - move to primary using SQL
+            from .db.models import ReadingSession
+            for sess in list(secondary.sessions):
+                self.session.execute(
+                    update(ReadingSession).where(ReadingSession.id == sess.id).values(book_id=primary.id)
+                )
+
+            # Annotations - move to primary using SQL
+            from .db.models import Annotation as AnnotationModel
+            for annotation in list(secondary.annotations):
+                self.session.execute(
+                    update(AnnotationModel).where(AnnotationModel.id == annotation.id).values(book_id=primary.id)
+                )
+
+            # Expire secondary so ORM doesn't cascade delete moved items
+            self.session.expire(secondary)
+            self.session.flush()
+
+            # Personal metadata - merge intelligently
+            if secondary.personal:
+                if primary.personal:
+                    # Keep higher rating
+                    if secondary.personal.rating and (
+                        not primary.personal.rating or
+                        secondary.personal.rating > primary.personal.rating
+                    ):
+                        primary.personal.rating = secondary.personal.rating
+                    # Keep "read" status over "unread"
+                    status_priority = {'read': 0, 'reading': 1, 'abandoned': 2, 'unread': 3}
+                    if status_priority.get(secondary.personal.reading_status, 3) < status_priority.get(primary.personal.reading_status, 3):
+                        primary.personal.reading_status = secondary.personal.reading_status
+                    # Keep higher progress
+                    if secondary.personal.reading_progress and (
+                        not primary.personal.reading_progress or
+                        secondary.personal.reading_progress > primary.personal.reading_progress
+                    ):
+                        primary.personal.reading_progress = secondary.personal.reading_progress
+                    # Keep favorite if either is favorite
+                    if secondary.personal.favorite:
+                        primary.personal.favorite = True
+                    # Keep earliest date_added
+                    if secondary.personal.date_added and (
+                        not primary.personal.date_added or
+                        secondary.personal.date_added < primary.personal.date_added
+                    ):
+                        primary.personal.date_added = secondary.personal.date_added
+                    # Keep dates if set
+                    if secondary.personal.date_started and not primary.personal.date_started:
+                        primary.personal.date_started = secondary.personal.date_started
+                    if secondary.personal.date_finished and not primary.personal.date_finished:
+                        primary.personal.date_finished = secondary.personal.date_finished
+                    # Merge personal_tags
+                    if secondary.personal.personal_tags:
+                        if primary.personal.personal_tags:
+                            primary.personal.personal_tags = list(set(
+                                primary.personal.personal_tags + secondary.personal.personal_tags
+                            ))
+                        else:
+                            primary.personal.personal_tags = secondary.personal.personal_tags
+                else:
+                    # Move secondary's personal metadata to primary
+                    secondary.personal.book_id = primary.id
+
+            # Delete secondary book
+            deleted_ids.append(secondary.id)
+            self.session.delete(secondary)
+
+        # Update primary's timestamp
+        primary.updated_at = utc_now()
+
+        self.session.commit()
+        logger.info(f"Merged {len(deleted_ids)} books into '{primary.title}' (ID: {primary.id})")
+
+        return primary, deleted_ids
+
+    def find_similar(
+        self,
+        book_id: int,
+        top_k: int = 10,
+        similarity_config: Optional[Any] = None,
+        filter_language: bool = True,
+    ) -> List[Tuple[Book, float]]:
+        """
+        Find books similar to the given book.
+
+        Uses semantic similarity based on content, metadata, etc.
+
+        Args:
+            book_id: ID of the query book
+            top_k: Number of similar books to return (default 10)
+            similarity_config: Optional BookSimilarity instance
+                             (default: balanced preset)
+            filter_language: If True, only return books in same language
+
+        Returns:
+            List of (book, similarity_score) tuples, sorted by similarity
+
+        Example:
+            >>> similar = lib.find_similar(42, top_k=5)
+            >>> for book, score in similar:
+            ...     print(f"{book.title}: {score:.2f}")
+        """
+        from ebk.similarity import BookSimilarity
+
+        # Get query book
+        query_book = self.get_book(book_id)
+        if not query_book:
+            logger.warning(f"Book {book_id} not found")
+            return []
+
+        # Get candidate books
+        candidates_query = self.query()
+        if filter_language and query_book.language:
+            candidates_query = candidates_query.filter_by_language(query_book.language)
+
+        candidates = candidates_query.all()
+
+        if not candidates:
+            return []
+
+        # Configure similarity - auto-detect sparse data
+        if similarity_config is None:
+            # Check if query book has extracted text
+            has_extracted_text = False
+            for file in query_book.files:
+                if file.extracted_text and file.extracted_text.content:
+                    if len(file.extracted_text.content) > 500:  # Minimum useful text
+                        has_extracted_text = True
+                        break
+
+            if has_extracted_text:
+                similarity_config = BookSimilarity().balanced()
+                logger.debug(f"Using balanced preset for book with extracted text")
+            else:
+                similarity_config = BookSimilarity().sparse_friendly()
+                logger.debug(f"Using sparse_friendly preset for book without extracted text")
+
+        # Fit on all candidates for performance
+        similarity_config.fit(candidates)
+
+        # Find similar books
+        results = similarity_config.find_similar(query_book, candidates, top_k=top_k)
+
+        logger.debug(
+            f"Found {len(results)} similar books to '{query_book.title}'"
+        )
+
+        return results
+
+    def compute_similarity_matrix(
+        self,
+        book_ids: Optional[List[int]] = None,
+        similarity_config: Optional[Any] = None,
+    ) -> Tuple[List[Book], Any]:
+        """
+        Compute pairwise similarity matrix for books.
+
+        Args:
+            book_ids: Optional list of book IDs (default: all books)
+            similarity_config: Optional BookSimilarity instance
+                             (default: balanced preset)
+
+        Returns:
+            Tuple of (books, similarity_matrix)
+            where similarity_matrix[i][j] = similarity(books[i], books[j])
+
+        Example:
+            >>> books, matrix = lib.compute_similarity_matrix()
+            >>> # matrix[0][1] is similarity between books[0] and books[1]
+        """
+        from ebk.similarity import BookSimilarity
+
+        # Get books
+        if book_ids:
+            books = [self.get_book(book_id) for book_id in book_ids]
+            books = [b for b in books if b is not None]  # Filter None
+        else:
+            books = self.query().all()
+
+        if not books:
+            logger.warning("No books found for similarity matrix")
+            return [], None
+
+        # Configure similarity
+        if similarity_config is None:
+            similarity_config = BookSimilarity().balanced()
+
+        # Fit and compute matrix
+        similarity_config.fit(books)
+        matrix = similarity_config.similarity_matrix(books)
+
+        logger.debug(f"Computed {len(books)}x{len(books)} similarity matrix")
+
+        return books, matrix
+
+
+class QueryBuilder:
+    """Fluent query builder for books."""
+
+    def __init__(self, session: Session):
+        self.session = session
+        self._query = session.query(Book)
+
+    def filter_by_title(self, title: str, exact: bool = False) -> 'QueryBuilder':
+        """Filter by title."""
+        if exact:
+            self._query = self._query.filter(Book.title == title)
+        else:
+            self._query = self._query.filter(Book.title.ilike(f"%{title}%"))
+        return self
+
+    def filter_by_author(self, author: str) -> 'QueryBuilder':
+        """Filter by author name."""
+        self._query = self._query.join(Book.authors).filter(
+            Author.name.ilike(f"%{author}%")
+        )
+        return self
+
+    def filter_by_subject(self, subject: str) -> 'QueryBuilder':
+        """Filter by subject."""
+        self._query = self._query.join(Book.subjects).filter(
+            Subject.name.ilike(f"%{subject}%")
+        )
+        return self
+
+    def filter_by_language(self, language: str) -> 'QueryBuilder':
+        """Filter by language code."""
+        self._query = self._query.filter(Book.language == language)
+        return self
+
+    def filter_by_publisher(self, publisher: str) -> 'QueryBuilder':
+        """Filter by publisher."""
+        self._query = self._query.filter(Book.publisher.ilike(f"%{publisher}%"))
+        return self
+
+    def filter_by_year(self, year: int) -> 'QueryBuilder':
+        """Filter by publication year.
+
+        Args:
+            year: Publication year (e.g., 1975)
+
+        Returns:
+            Self for chaining
+        """
+        # publication_date can be "YYYY", "YYYY-MM", or "YYYY-MM-DD"
+        # So we match if it starts with the year
+        year_str = str(year)
+        self._query = self._query.filter(Book.publication_date.like(f"{year_str}%"))
+        return self
+
+    def filter_by_text(self, search_text: str) -> 'QueryBuilder':
+        """Filter by full-text search.
+
+        Uses FTS5 to search across title, description, and extracted text.
+
+        Args:
+            search_text: Text to search for
+
+        Returns:
+            Self for chaining
+        """
+        from sqlalchemy import text as sql_text
+
+        # Query FTS5 table for matching book IDs
+        result = self.session.execute(
+            sql_text("""
+            SELECT book_id
+            FROM books_fts
+            WHERE books_fts MATCH :query
+            ORDER BY rank
+            """),
+            {"query": search_text}
+        )
+        book_ids = [row[0] for row in result]
+
+        if book_ids:
+            self._query = self._query.filter(Book.id.in_(book_ids))
+        else:
+            # No matches - ensure query returns empty
+            self._query = self._query.filter(Book.id == -1)
+
+        return self
+
+    def filter_by_reading_status(self, status: str) -> 'QueryBuilder':
+        """Filter by reading status."""
+        self._query = self._query.join(Book.personal).filter(
+            PersonalMetadata.reading_status == status
+        )
+        return self
+
+    def filter_by_rating(self, min_rating: int, max_rating: int = 5) -> 'QueryBuilder':
+        """Filter by rating range."""
+        self._query = self._query.join(Book.personal).filter(
+            and_(
+                PersonalMetadata.rating >= min_rating,
+                PersonalMetadata.rating <= max_rating
+            )
+        )
+        return self
+
+    def filter_by_favorite(self, is_favorite: bool = True) -> 'QueryBuilder':
+        """Filter by favorite status."""
+        from sqlalchemy import or_
+        if is_favorite:
+            # Only books explicitly marked as favorite
+            self._query = self._query.join(Book.personal).filter(
+                PersonalMetadata.favorite == True
+            )
+        else:
+            # Books not favorited (including those without PersonalMetadata)
+            self._query = self._query.outerjoin(Book.personal).filter(
+                or_(
+                    PersonalMetadata.favorite == False,
+                    PersonalMetadata.favorite.is_(None)
+                )
+            )
+        return self
+
+    def filter_by_format(self, format_name: str) -> 'QueryBuilder':
+        """Filter by file format (e.g., 'pdf', 'epub')."""
+        from .db.models import File
+        self._query = self._query.join(Book.files).filter(
+            File.format.ilike(f'%{format_name}%')
+        )
+        return self
+
+    def order_by(self, field: str, desc: bool = False) -> 'QueryBuilder':
+        """
+        Order results.
+
+        Args:
+            field: Field name (title, created_at, publication_date)
+            desc: Descending order if True
+        """
+        field_map = {
+            'title': Book.title,
+            'created_at': Book.created_at,
+            'publication_date': Book.publication_date,
+        }
+
+        if field in field_map:
+            order_field = field_map[field]
+            if desc:
+                order_field = order_field.desc()
+            self._query = self._query.order_by(order_field)
+
+        return self
+
+    def limit(self, limit: int) -> 'QueryBuilder':
+        """Limit number of results."""
+        self._query = self._query.limit(limit)
+        return self
+
+    def offset(self, offset: int) -> 'QueryBuilder':
+        """Set result offset."""
+        self._query = self._query.offset(offset)
+        return self
+
+    def all(self) -> List[Book]:
+        """Execute query and return all results."""
+        return self._query.all()
+
+    def first(self) -> Optional[Book]:
+        """Execute query and return first result."""
+        return self._query.first()
+
+    def count(self) -> int:
+        """Get count of matching books."""
+        return self._query.count()