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

ebk/ai/metadata_enrichment.py

@@ -0,0 +1,396 @@
+"""
+Metadata Enrichment Service using LLM providers.
+
+Provides:
+- Metadata inference from text
+- Auto-tagging
+- Subject categorization
+- Description generation
+- Difficulty level assessment
+"""
+
+import json
+from typing import Dict, Any, List, Optional
+from dataclasses import dataclass
+from pathlib import Path
+
+from .llm_providers.base import BaseLLMProvider
+
+
+@dataclass
+class EnrichedMetadata:
+    """Enriched metadata generated by LLM."""
+
+    # Inferred metadata
+    title: Optional[str] = None
+    authors: Optional[List[str]] = None
+    subjects: Optional[List[str]] = None
+    description: Optional[str] = None
+    keywords: Optional[List[str]] = None
+
+    # Auto-generated tags
+    tags: Optional[List[str]] = None
+    categories: Optional[List[str]] = None
+
+    # Content analysis
+    difficulty_level: Optional[str] = None  # beginner, intermediate, advanced
+    reading_time_minutes: Optional[int] = None
+    target_audience: Optional[str] = None
+
+    # Quality metrics
+    confidence_score: float = 0.0  # 0.0 to 1.0
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary."""
+        return {
+            k: v for k, v in {
+                "title": self.title,
+                "authors": self.authors,
+                "subjects": self.subjects,
+                "description": self.description,
+                "keywords": self.keywords,
+                "tags": self.tags,
+                "categories": self.categories,
+                "difficulty_level": self.difficulty_level,
+                "reading_time_minutes": self.reading_time_minutes,
+                "target_audience": self.target_audience,
+                "confidence_score": self.confidence_score,
+            }.items() if v is not None
+        }
+
+
+class MetadataEnrichmentService:
+    """
+    Service for enriching book metadata using LLM.
+
+    Can work with:
+    - Extracted text from PDFs/EPUBs
+    - Existing metadata (title, authors, etc.)
+    - Combination of both
+    """
+
+    def __init__(self, provider: BaseLLMProvider):
+        """
+        Initialize service with LLM provider.
+
+        Args:
+            provider: LLM provider instance (e.g., OllamaProvider)
+        """
+        self.provider = provider
+
+    async def infer_metadata_from_text(
+        self,
+        text: str,
+        existing_metadata: Optional[Dict[str, Any]] = None,
+        max_text_length: int = 5000
+    ) -> EnrichedMetadata:
+        """
+        Infer metadata from extracted text.
+
+        Args:
+            text: Extracted text from book (truncated if too long)
+            existing_metadata: Any existing metadata to enhance
+            max_text_length: Maximum text length to send to LLM
+
+        Returns:
+            EnrichedMetadata with inferred fields
+        """
+        # Truncate text if too long
+        if len(text) > max_text_length:
+            text = text[:max_text_length] + "..."
+
+        # Build prompt
+        prompt = self._build_metadata_inference_prompt(text, existing_metadata)
+
+        # Define expected schema
+        schema = {
+            "type": "object",
+            "properties": {
+                "title": {"type": "string"},
+                "authors": {"type": "array", "items": {"type": "string"}},
+                "subjects": {"type": "array", "items": {"type": "string"}},
+                "description": {"type": "string"},
+                "keywords": {"type": "array", "items": {"type": "string"}},
+                "difficulty_level": {"type": "string", "enum": ["beginner", "intermediate", "advanced"]},
+                "target_audience": {"type": "string"},
+                "confidence_score": {"type": "number", "minimum": 0, "maximum": 1},
+            }
+        }
+
+        try:
+            result = await self.provider.complete_json(
+                prompt=prompt,
+                schema=schema,
+                temperature=0.3,  # Lower temperature for more consistent metadata
+            )
+
+            return EnrichedMetadata(
+                title=result.get("title"),
+                authors=result.get("authors"),
+                subjects=result.get("subjects"),
+                description=result.get("description"),
+                keywords=result.get("keywords"),
+                difficulty_level=result.get("difficulty_level"),
+                target_audience=result.get("target_audience"),
+                confidence_score=result.get("confidence_score", 0.7),
+            )
+
+        except Exception as e:
+            print(f"Metadata inference failed: {e}")
+            return EnrichedMetadata(confidence_score=0.0)
+
+    async def generate_tags(
+        self,
+        title: str,
+        authors: Optional[List[str]] = None,
+        subjects: Optional[List[str]] = None,
+        description: Optional[str] = None,
+        text_sample: Optional[str] = None,
+        max_tags: int = 15
+    ) -> List[str]:
+        """
+        Generate relevant tags for a book.
+
+        Args:
+            title: Book title
+            authors: List of authors
+            subjects: Existing subjects/topics
+            description: Book description
+            text_sample: Sample text from book
+            max_tags: Maximum number of tags to generate
+
+        Returns:
+            List of tags
+        """
+        prompt = f"""Generate up to {max_tags} relevant tags for this book.
+
+Title: {title}
+Authors: {', '.join(authors or [])}
+Subjects: {', '.join(subjects or [])}
+Description: {description or 'N/A'}
+
+{f'Text Sample: {text_sample[:1000]}...' if text_sample else ''}
+
+Generate tags that would help someone find this book. Include:
+- Genre (fiction, non-fiction, textbook, reference, etc.)
+- Topics and themes
+- Reading level (introductory, advanced, comprehensive, etc.)
+- Format type (handbook, guide, manual, tutorial, etc.)
+- Domain (programming, mathematics, history, science, etc.)
+
+Return as JSON array: ["tag1", "tag2", ...]"""
+
+        try:
+            result = await self.provider.complete_json(prompt, temperature=0.5)
+
+            # Handle both array and object responses
+            if isinstance(result, list):
+                tags = result
+            elif isinstance(result, dict) and "tags" in result:
+                tags = result["tags"]
+            else:
+                tags = []
+
+            # Clean and deduplicate tags
+            tags = [str(tag).strip().lower() for tag in tags if tag]
+            tags = list(dict.fromkeys(tags))  # Deduplicate while preserving order
+
+            return tags[:max_tags]
+
+        except Exception as e:
+            print(f"Tag generation failed: {e}")
+            return []
+
+    async def categorize(
+        self,
+        title: str,
+        subjects: Optional[List[str]] = None,
+        description: Optional[str] = None,
+    ) -> List[str]:
+        """
+        Categorize book into standard categories.
+
+        Args:
+            title: Book title
+            subjects: Existing subjects
+            description: Book description
+
+        Returns:
+            List of categories (e.g., ['Computer Science', 'Programming', 'Software Engineering'])
+        """
+        prompt = f"""Categorize this book into standard academic/library categories.
+
+Title: {title}
+Subjects: {', '.join(subjects or [])}
+Description: {description or 'N/A'}
+
+Use standard categories like:
+- Computer Science, Mathematics, Physics, Chemistry, Biology
+- Engineering, Medicine, Law, Business
+- History, Philosophy, Psychology, Sociology
+- Literature, Art, Music
+- Programming, Data Science, Machine Learning, AI
+
+Return 2-5 relevant categories as JSON array: ["Category1", "Category2", ...]"""
+
+        try:
+            result = await self.provider.complete_json(prompt, temperature=0.3)
+
+            if isinstance(result, list):
+                categories = result
+            elif isinstance(result, dict) and "categories" in result:
+                categories = result["categories"]
+            else:
+                categories = []
+
+            return [str(cat).strip() for cat in categories if cat]
+
+        except Exception as e:
+            print(f"Categorization failed: {e}")
+            return []
+
+    async def enhance_description(
+        self,
+        title: str,
+        existing_description: Optional[str] = None,
+        text_sample: Optional[str] = None,
+        max_length: int = 500
+    ) -> Optional[str]:
+        """
+        Generate or enhance book description.
+
+        Args:
+            title: Book title
+            existing_description: Current description (if any)
+            text_sample: Sample text from book
+            max_length: Maximum description length
+
+        Returns:
+            Enhanced description
+        """
+        if existing_description and len(existing_description) > max_length:
+            # Already have a good description
+            return existing_description
+
+        prompt = f"""Write a clear, informative description for this book.
+
+Title: {title}
+{f'Current Description: {existing_description}' if existing_description else ''}
+{f'Text Sample: {text_sample[:2000]}...' if text_sample else ''}
+
+Write a {max_length}-character description that:
+1. Explains what the book is about
+2. Identifies the target audience
+3. Highlights key topics covered
+4. Mentions the approach/style (e.g., practical guide, theoretical text, reference manual)
+
+Return just the description text, no JSON."""
+
+        try:
+            response = await self.provider.complete(prompt, temperature=0.5)
+            description = response.content.strip()
+
+            # Remove quotes if LLM wrapped it
+            if description.startswith('"') and description.endswith('"'):
+                description = description[1:-1]
+
+            return description[:max_length]
+
+        except Exception as e:
+            print(f"Description generation failed: {e}")
+            return existing_description
+
+    async def assess_difficulty(
+        self,
+        text_sample: str,
+        subjects: Optional[List[str]] = None
+    ) -> str:
+        """
+        Assess difficulty level of book.
+
+        Args:
+            text_sample: Sample text from book
+            subjects: Book subjects/topics
+
+        Returns:
+            Difficulty level: 'beginner', 'intermediate', or 'advanced'
+        """
+        prompt = f"""Assess the difficulty level of this text.
+
+Subjects: {', '.join(subjects or [])}
+
+Text Sample:
+{text_sample[:2000]}
+
+Consider:
+- Vocabulary complexity
+- Concept difficulty
+- Prerequisites assumed
+- Mathematical/technical content
+
+Return one of: "beginner", "intermediate", "advanced"
+
+Return as JSON: {{"level": "..."}}"""
+
+        try:
+            result = await self.provider.complete_json(prompt, temperature=0.2)
+            level = result.get("level", "intermediate")
+
+            if level not in ["beginner", "intermediate", "advanced"]:
+                level = "intermediate"
+
+            return level
+
+        except Exception as e:
+            print(f"Difficulty assessment failed: {e}")
+            return "intermediate"
+
+    def _build_metadata_inference_prompt(
+        self,
+        text: str,
+        existing_metadata: Optional[Dict[str, Any]] = None
+    ) -> str:
+        """Build prompt for metadata inference."""
+
+        prompt = """Analyze this text and infer metadata about the book.
+
+Text Sample:
+---
+{text}
+---
+
+{existing}
+
+Extract or infer:
+1. Title (if not provided)
+2. Authors (if mentioned)
+3. Subjects/topics (main themes and topics covered)
+4. Description (2-3 sentence summary)
+5. Keywords (10-15 relevant search terms)
+6. Difficulty level (beginner/intermediate/advanced)
+7. Target audience (who should read this)
+
+Respond with JSON matching this schema:
+{{
+  "title": "string",
+  "authors": ["author1", "author2"],
+  "subjects": ["subject1", "subject2"],
+  "description": "string",
+  "keywords": ["keyword1", "keyword2"],
+  "difficulty_level": "beginner|intermediate|advanced",
+  "target_audience": "string",
+  "confidence_score": 0.0-1.0
+}}
+
+Only include fields you can confidently infer. Set confidence_score based on how much information was available."""
+
+        existing_str = ""
+        if existing_metadata:
+            existing_str = f"""
+Existing Metadata (enhance if possible):
+Title: {existing_metadata.get('title', 'Unknown')}
+Authors: {', '.join(existing_metadata.get('authors', []))}
+Subjects: {', '.join(existing_metadata.get('subjects', []))}
+"""
+
+        return prompt.format(text=text, existing=existing_str)