ebk 0.3.1__py3-none-any.whl → 0.3.2__py3-none-any.whl

ebk/similarity/extractors.py

@@ -0,0 +1,168 @@
+"""Concrete extractor implementations."""
+
+from typing import Optional, Set
+
+from ebk.db.models import Book
+from ebk.similarity.base import Extractor
+
+
+class ContentExtractor(Extractor[str]):
+    """Extracts full text content from a book.
+
+    Uses extracted_text from primary file if available, otherwise combines
+    title and description.
+    """
+
+    def extract(self, book: Book) -> str:
+        """Extract text content from book.
+
+        Args:
+            book: Book to extract from
+
+        Returns:
+            Full text content as string
+        """
+        # Try to get extracted text from primary file
+        if book.files:
+            for file in book.files:
+                if file.extracted_text and file.extracted_text.full_text:
+                    return file.extracted_text.full_text
+
+        # Fallback to title + description
+        parts = []
+        if book.title:
+            parts.append(book.title)
+        if book.description:
+            parts.append(book.description)
+
+        return " ".join(parts)
+
+
+class AuthorsExtractor(Extractor[Set[str]]):
+    """Extracts set of author names from a book."""
+
+    def extract(self, book: Book) -> Set[str]:
+        """Extract author names from book.
+
+        Args:
+            book: Book to extract from
+
+        Returns:
+            Set of author names (normalized to lowercase)
+        """
+        if not book.authors:
+            return set()
+
+        return {author.name.lower() for author in book.authors}
+
+
+class SubjectsExtractor(Extractor[Set[str]]):
+    """Extracts set of subjects/tags from a book."""
+
+    def extract(self, book: Book) -> Set[str]:
+        """Extract subjects from book.
+
+        Args:
+            book: Book to extract from
+
+        Returns:
+            Set of subject names (normalized to lowercase)
+        """
+        if not book.subjects:
+            return set()
+
+        return {subject.name.lower() for subject in book.subjects}
+
+
+class PublicationYearExtractor(Extractor[Optional[int]]):
+    """Extracts publication year from a book."""
+
+    def extract(self, book: Book) -> Optional[int]:
+        """Extract publication year from book.
+
+        Args:
+            book: Book to extract from
+
+        Returns:
+            Publication year as int, or None if not available
+        """
+        if not book.publication_date:
+            return None
+
+        # Handle various date formats
+        date_str = str(book.publication_date)
+
+        # Try to extract year
+        if len(date_str) >= 4:
+            try:
+                return int(date_str[:4])
+            except ValueError:
+                return None
+
+        return None
+
+
+class LanguageExtractor(Extractor[Optional[str]]):
+    """Extracts language code from a book."""
+
+    def extract(self, book: Book) -> Optional[str]:
+        """Extract language from book.
+
+        Args:
+            book: Book to extract from
+
+        Returns:
+            Language code (normalized to lowercase), or None
+        """
+        if not book.language:
+            return None
+
+        return book.language.lower()
+
+
+class PublisherExtractor(Extractor[Optional[str]]):
+    """Extracts publisher name from a book."""
+
+    def extract(self, book: Book) -> Optional[str]:
+        """Extract publisher from book.
+
+        Args:
+            book: Book to extract from
+
+        Returns:
+            Publisher name (normalized to lowercase), or None
+        """
+        if not book.publisher:
+            return None
+
+        return book.publisher.lower()
+
+
+class PageCountExtractor(Extractor[Optional[int]]):
+    """Extracts page count from a book."""
+
+    def extract(self, book: Book) -> Optional[int]:
+        """Extract page count from book.
+
+        Args:
+            book: Book to extract from
+
+        Returns:
+            Page count, or None if not available
+        """
+        return book.page_count
+
+
+class DescriptionExtractor(Extractor[str]):
+    """Extracts description/summary from a book."""
+
+    def extract(self, book: Book) -> str:
+        """Extract description from book.
+
+        Args:
+            book: Book to extract from
+
+        Returns:
+            Description text (empty string if not available)
+        """
+        return book.description or ""

ebk/similarity/metrics.py

@@ -0,0 +1,376 @@
+"""Concrete metric implementations."""
+
+import math
+import pickle
+from pathlib import Path
+from typing import Dict, Optional, Set
+
+import numpy as np
+from sklearn.feature_extraction.text import TfidfVectorizer
+from sklearn.metrics.pairwise import cosine_similarity
+
+from ebk.similarity.base import Metric
+
+
+class JaccardMetric(Metric[Set[str]]):
+    """Jaccard similarity for sets.
+
+    Computes |A ∩ B| / |A ∪ B|
+
+    Returns:
+        1.0 if sets are identical
+        0.0 if sets have no overlap
+    """
+
+    def similarity(self, value1: Set[str], value2: Set[str]) -> float:
+        """Compute Jaccard similarity between two sets.
+
+        Args:
+            value1: First set
+            value2: Second set
+
+        Returns:
+            Jaccard similarity in [0, 1]
+        """
+        if not value1 and not value2:
+            return 1.0  # Both empty = identical
+
+        if not value1 or not value2:
+            return 0.0  # One empty = no overlap
+
+        intersection = len(value1 & value2)
+        union = len(value1 | value2)
+
+        if union == 0:
+            return 0.0
+
+        return intersection / union
+
+
+class ExactMatchMetric(Metric):
+    """Exact match metric for any comparable values.
+
+    Returns:
+        1.0 if values are equal
+        0.0 if values are different
+    """
+
+    def similarity(self, value1, value2) -> float:
+        """Compute exact match similarity.
+
+        Args:
+            value1: First value
+            value2: Second value
+
+        Returns:
+            1.0 if equal, 0.0 otherwise
+        """
+        if value1 is None or value2 is None:
+            return 0.0
+
+        return 1.0 if value1 == value2 else 0.0
+
+
+class TemporalDecayMetric(Metric[Optional[int]]):
+    """Gaussian decay based on time difference.
+
+    Similarity decays as Gaussian: exp(-((y1 - y2) / sigma)^2)
+
+    Attributes:
+        sigma: Standard deviation for Gaussian (controls decay rate)
+               Default 10 years means ~60% similarity for 10-year gap
+    """
+
+    def __init__(self, sigma: float = 10.0):
+        """Initialize temporal decay metric.
+
+        Args:
+            sigma: Standard deviation in years (default 10.0)
+        """
+        self.sigma = sigma
+
+    def similarity(self, value1: Optional[int], value2: Optional[int]) -> float:
+        """Compute temporal similarity with Gaussian decay.
+
+        Args:
+            value1: First year
+            value2: Second year
+
+        Returns:
+            Similarity in [0, 1] based on Gaussian decay
+        """
+        if value1 is None or value2 is None:
+            return 0.0
+
+        diff = abs(value1 - value2)
+        return math.exp(-((diff / self.sigma) ** 2))
+
+
+class NumericProximityMetric(Metric[Optional[int]]):
+    """Similarity based on numeric proximity with normalization.
+
+    Computes: 1 - |v1 - v2| / max_diff
+
+    Useful for page counts, ratings, etc.
+
+    Attributes:
+        max_diff: Maximum expected difference for normalization
+    """
+
+    def __init__(self, max_diff: float):
+        """Initialize numeric proximity metric.
+
+        Args:
+            max_diff: Maximum expected difference (e.g., 1000 pages)
+        """
+        self.max_diff = max_diff
+
+    def similarity(self, value1: Optional[int], value2: Optional[int]) -> float:
+        """Compute numeric proximity similarity.
+
+        Args:
+            value1: First value
+            value2: Second value
+
+        Returns:
+            Similarity in [0, 1] based on proximity
+        """
+        if value1 is None or value2 is None:
+            return 0.0
+
+        diff = abs(value1 - value2)
+        normalized = min(diff / self.max_diff, 1.0)
+        return 1.0 - normalized
+
+
+class TfidfMetric(Metric[str]):
+    """TF-IDF cosine similarity for text.
+
+    This metric needs fitting to build vocabulary and cache vectors.
+
+    Attributes:
+        max_features: Maximum number of features for TF-IDF (default 5000)
+        min_df: Minimum document frequency (default 2)
+        max_df: Maximum document frequency (default 0.95)
+    """
+
+    def __init__(
+        self,
+        max_features: int = 5000,
+        min_df: int = 2,
+        max_df: float = 0.95,
+    ):
+        """Initialize TF-IDF metric.
+
+        Args:
+            max_features: Maximum number of features (default 5000)
+            min_df: Minimum document frequency (default 2)
+            max_df: Maximum document frequency (default 0.95)
+        """
+        self.max_features = max_features
+        self.min_df = min_df
+        self.max_df = max_df
+
+        self.vectorizer = TfidfVectorizer(
+            max_features=max_features,
+            min_df=min_df,
+            max_df=max_df,
+            stop_words="english",
+        )
+
+        self._vectors: Dict[int, np.ndarray] = {}
+        self._fitted = False
+
+    def fit(self, data: Dict[int, str]) -> None:
+        """Fit vectorizer and cache all vectors.
+
+        This dramatically speeds up similarity computation by pre-computing
+        TF-IDF vectors for all books.
+
+        Args:
+            data: Dictionary mapping book IDs to text content
+        """
+        if not data:
+            return
+
+        # Fit vectorizer on all texts
+        book_ids = list(data.keys())
+        texts = [data[book_id] for book_id in book_ids]
+
+        # Fit and transform
+        vectors = self.vectorizer.fit_transform(texts)
+
+        # Cache sparse vectors by book_id
+        for book_id, vector in zip(book_ids, vectors):
+            self._vectors[book_id] = vector
+
+        self._fitted = True
+
+    def similarity(self, value1: str, value2: str) -> float:
+        """Compute TF-IDF cosine similarity.
+
+        If not fitted, transforms texts on-the-fly (slow).
+        If fitted, uses cached vectors (fast).
+
+        Args:
+            value1: First text
+            value2: Second text
+
+        Returns:
+            Cosine similarity in [0, 1]
+        """
+        if not value1 or not value2:
+            return 0.0
+
+        # Transform texts to vectors
+        if not self._fitted:
+            # Not fitted - transform on the fly (slow path)
+            try:
+                vectors = self.vectorizer.fit_transform([value1, value2])
+                v1, v2 = vectors[0], vectors[1]
+            except ValueError:
+                # Empty vocabulary
+                return 0.0
+        else:
+            # Fitted - transform using learned vocabulary
+            try:
+                v1 = self.vectorizer.transform([value1])
+                v2 = self.vectorizer.transform([value2])
+            except ValueError:
+                return 0.0
+
+        # Compute cosine similarity
+        sim = cosine_similarity(v1, v2)[0, 0]
+
+        # Ensure [0, 1] range (cosine can be negative for sparse vectors)
+        return max(0.0, min(1.0, sim))
+
+    def similarity_from_cache(self, book1_id: int, book2_id: int) -> float:
+        """Fast similarity using pre-computed vectors.
+
+        Args:
+            book1_id: ID of first book
+            book2_id: ID of second book
+
+        Returns:
+            Cosine similarity in [0, 1]
+
+        Raises:
+            KeyError: If book IDs not in cache (need to call fit() first)
+        """
+        if not self._fitted:
+            raise RuntimeError("Must call fit() before similarity_from_cache()")
+
+        v1 = self._vectors[book1_id]
+        v2 = self._vectors[book2_id]
+
+        sim = cosine_similarity(v1, v2)[0, 0]
+        return max(0.0, min(1.0, sim))
+
+    def save(self, path: Path) -> None:
+        """Save fitted state to disk.
+
+        Args:
+            path: Path to save to (will create .pkl file)
+        """
+        if not self._fitted:
+            raise RuntimeError("Must call fit() before save()")
+
+        state = {
+            "vectorizer": self.vectorizer,
+            "vectors": self._vectors,
+            "max_features": self.max_features,
+            "min_df": self.min_df,
+            "max_df": self.max_df,
+        }
+
+        with open(path, "wb") as f:
+            pickle.dump(state, f)
+
+    def load(self, path: Path) -> None:
+        """Load fitted state from disk.
+
+        Args:
+            path: Path to load from
+        """
+        with open(path, "rb") as f:
+            state = pickle.load(f)
+
+        self.vectorizer = state["vectorizer"]
+        self._vectors = state["vectors"]
+        self.max_features = state["max_features"]
+        self.min_df = state["min_df"]
+        self.max_df = state["max_df"]
+        self._fitted = True
+
+
+class CosineMetric(Metric[str]):
+    """Simple cosine similarity without TF-IDF weighting.
+
+    Uses CountVectorizer instead of TF-IDF. Faster but less accurate
+    than TfidfMetric.
+    """
+
+    def __init__(self, max_features: int = 5000):
+        """Initialize cosine metric.
+
+        Args:
+            max_features: Maximum number of features (default 5000)
+        """
+        from sklearn.feature_extraction.text import CountVectorizer
+
+        self.max_features = max_features
+        self.vectorizer = CountVectorizer(
+            max_features=max_features,
+            stop_words="english",
+        )
+        self._vectors: Dict[int, np.ndarray] = {}
+        self._fitted = False
+
+    def fit(self, data: Dict[int, str]) -> None:
+        """Fit vectorizer and cache all vectors.
+
+        Args:
+            data: Dictionary mapping book IDs to text content
+        """
+        if not data:
+            return
+
+        book_ids = list(data.keys())
+        texts = [data[book_id] for book_id in book_ids]
+
+        vectors = self.vectorizer.fit_transform(texts)
+
+        for book_id, vector in zip(book_ids, vectors):
+            self._vectors[book_id] = vector
+
+        self._fitted = True
+
+    def similarity(self, value1: str, value2: str) -> float:
+        """Compute cosine similarity.
+
+        Args:
+            value1: First text
+            value2: Second text
+
+        Returns:
+            Cosine similarity in [0, 1]
+        """
+        if not value1 or not value2:
+            return 0.0
+
+        if not self._fitted:
+            try:
+                vectors = self.vectorizer.fit_transform([value1, value2])
+                v1, v2 = vectors[0], vectors[1]
+            except ValueError:
+                return 0.0
+        else:
+            try:
+                v1 = self.vectorizer.transform([value1])
+                v2 = self.vectorizer.transform([value2])
+            except ValueError:
+                return 0.0
+
+        sim = cosine_similarity(v1, v2)[0, 0]
+        return max(0.0, min(1.0, sim))

ebk/vfs/__init__.py

@@ -0,0 +1,101 @@
+"""Virtual File System for navigating the library database.
+
+The VFS provides a filesystem-like interface for browsing and interacting
+with the ebook library. It maps database entities to a hierarchical structure
+that can be navigated with familiar shell commands.
+
+Architecture:
+
+    ```
+    /                           # Root (RootNode)
+    ├── books/                  # All books (BooksDirectoryNode)
+    │   ├── 1/                 # Book 1 (BookNode)
+    │   │   ├── title          # Metadata file (TitleFileNode)
+    │   │   ├── authors        # Metadata file (AuthorsFileNode)
+    │   │   ├── description    # Metadata file
+    │   │   ├── text           # Extracted text (TextFileNode)
+    │   │   ├── files/         # Physical files (FilesDirectoryNode)
+    │   │   │   ├── book.pdf
+    │   │   │   └── book.epub
+    │   │   ├── similar/       # Similar books (SimilarDirectoryNode)
+    │   │   ├── annotations/   # User annotations
+    │   │   └── covers/        # Cover images
+    │   └── 2/
+    ├── authors/               # Browse by author (AuthorsDirectoryNode)
+    │   └── knuth-donald/      # Books by this author
+    ├── subjects/              # Browse by subject
+    └── series/                # Browse by series
+    ```
+
+Node Types:
+
+    - Node: Base class for all VFS entries
+    - DirectoryNode: Can contain children (cd into them)
+    - FileNode: Leaf nodes with content (cat them)
+    - VirtualNode: Dynamically computed (e.g., /books/, /similar/)
+    - SymlinkNode: Links to other nodes
+
+Path Resolution:
+
+    The PathResolver handles navigation:
+    - Absolute paths: /books/42/title
+    - Relative paths: ../other, ./files
+    - Special: ., .., ~ (home = /)
+    - Symlink following
+    - Tab completion support
+
+Usage Example:
+
+    ```python
+    from ebk.library_db import Library
+    from ebk.vfs import LibraryVFS
+
+    # Create VFS for a library
+    lib = Library.open("/path/to/library")
+    vfs = LibraryVFS(lib)
+
+    # Navigate
+    root = vfs.root
+    books_dir = vfs.resolver.resolve("/books", root)
+    book_node = vfs.resolver.resolve("/books/42", root)
+
+    # List children
+    children = books_dir.list_children()  # All books
+    for child in children:
+        print(child.name, child.get_info())
+
+    # Read file content
+    title_node = vfs.resolver.resolve("/books/42/title", root)
+    if isinstance(title_node, FileNode):
+        content = title_node.read_content()
+        print(content)
+    ```
+"""
+
+from ebk.vfs.base import (
+    Node,
+    DirectoryNode,
+    FileNode,
+    VirtualNode,
+    SymlinkNode,
+    NodeType,
+)
+from ebk.vfs.resolver import PathResolver, PathError, NotADirectoryError, NotFoundError
+from ebk.vfs.library_vfs import LibraryVFS
+
+__all__ = [
+    # Main entry point
+    "LibraryVFS",
+    # Core classes
+    "Node",
+    "DirectoryNode",
+    "FileNode",
+    "VirtualNode",
+    "SymlinkNode",
+    "NodeType",
+    # Path resolution
+    "PathResolver",
+    "PathError",
+    "NotADirectoryError",
+    "NotFoundError",
+]