scitex 2.14.0__py3-none-any.whl → 2.16.0__py3-none-any.whl

scitex/scholar/core/_mixins/_project_handlers.py

@@ -0,0 +1,125 @@
+#!/usr/bin/env python3
+# Timestamp: "2026-01-24 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-python/src/scitex/scholar/core/_mixins/_project_handlers.py
+
+"""
+Project handler mixin for Scholar class.
+
+Provides project management functionality.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from scitex import logging
+
+logger = logging.getLogger(__name__)
+
+
+class ProjectHandlerMixin:
+    """Mixin providing project management methods."""
+
+    def _ensure_project_exists(
+        self, project: str, description: Optional[str] = None
+    ) -> Path:
+        """Ensure project directory exists, create if needed (PRIVATE).
+
+        Args:
+            project: Project name
+            description: Optional project description
+
+        Returns
+        -------
+            Path to the project directory
+        """
+        project_dir = self.config.get_library_project_dir(project)
+        info_dir = project_dir / "info"
+
+        if not project_dir.exists():
+            project_dir.mkdir(parents=True, exist_ok=True)
+            logger.info(f"{self.name}: Auto-created project directory: {project}")
+
+        info_dir.mkdir(parents=True, exist_ok=True)
+
+        old_metadata_file = project_dir / "project_metadata.json"
+        metadata_file = info_dir / "project_metadata.json"
+
+        if old_metadata_file.exists() and not metadata_file.exists():
+            shutil.move(str(old_metadata_file), str(metadata_file))
+            logger.info(f"{self.name}: Moved project metadata to info directory")
+
+        if not metadata_file.exists():
+            metadata = {
+                "name": project,
+                "description": description or f"Papers for {project} project",
+                "created": datetime.now().isoformat(),
+                "created_by": "SciTeX Scholar",
+                "auto_created": True,
+            }
+
+            with open(metadata_file, "w") as f:
+                json.dump(metadata, f, indent=2)
+
+            logger.info(
+                f"{self.name}: Created project metadata in info directory: {project}"
+            )
+
+        return project_dir
+
+    def _create_project_metadata(
+        self, project: str, description: Optional[str] = None
+    ) -> Path:
+        """Create project directory and metadata (PRIVATE).
+
+        DEPRECATED: Use _ensure_project_exists instead.
+
+        Args:
+            project: Project name
+            description: Optional project description
+
+        Returns
+        -------
+            Path to the created project directory
+        """
+        return self._ensure_project_exists(project, description)
+
+    def list_projects(self) -> List[Dict[str, Any]]:
+        """List all projects in the Scholar library.
+
+        Returns
+        -------
+            List of project information dictionaries
+        """
+        library_dir = self.config.path_manager.library_dir
+        projects = []
+
+        for item in library_dir.iterdir():
+            if item.is_dir() and item.name != "MASTER":
+                project_info = {
+                    "name": item.name,
+                    "path": str(item),
+                    "papers_count": len(list(item.glob("*"))),
+                    "created": None,
+                    "description": None,
+                }
+
+                metadata_file = item / "project_metadata.json"
+                if metadata_file.exists():
+                    try:
+                        with open(metadata_file) as f:
+                            metadata = json.load(f)
+                        project_info.update(metadata)
+                    except Exception as e:
+                        logger.debug(f"Failed to load metadata for {item.name}: {e}")
+
+                projects.append(project_info)
+
+        return sorted(projects, key=lambda x: x["name"])
+
+
+# EOF

scitex/scholar/core/_mixins/_savers.py

@@ -0,0 +1,69 @@
+#!/usr/bin/env python3
+# Timestamp: "2026-01-24 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-python/src/scitex/scholar/core/_mixins/_savers.py
+
+"""
+Saver mixin for Scholar class.
+
+Provides methods for saving papers to library and BibTeX format.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, List, Optional, Union
+
+from scitex import logging
+
+if TYPE_CHECKING:
+    from ..Papers import Papers
+
+logger = logging.getLogger(__name__)
+
+
+class SaverMixin:
+    """Mixin providing paper saving methods."""
+
+    def save_papers_to_library(self, papers: Papers) -> List[str]:
+        """Save papers collection to library.
+
+        Args:
+            papers: Papers collection to save
+
+        Returns
+        -------
+            List of paper IDs saved
+        """
+        saved_ids = []
+        for paper in papers:
+            try:
+                paper_id = self._library.save_paper(paper)
+                saved_ids.append(paper_id)
+            except Exception as e:
+                logger.warning(f"{self.name}: Failed to save paper: {e}")
+
+        logger.info(
+            f"{self.name}: Saved {len(saved_ids)}/{len(papers)} papers to library"
+        )
+        return saved_ids
+
+    def save_papers_as_bibtex(
+        self, papers: Papers, output_path: Optional[Union[str, Path]] = None
+    ) -> str:
+        """Save papers to BibTeX format with enrichment metadata.
+
+        Args:
+            papers: Papers collection to save
+            output_path: Optional path to save the BibTeX file
+
+        Returns
+        -------
+            BibTeX content as string with enrichment metadata included
+        """
+        from ..storage.BibTeXHandler import BibTeXHandler
+
+        bibtex_handler = BibTeXHandler(project=self.project, config=self.config)
+        return bibtex_handler.papers_to_bibtex(papers, output_path)
+
+
+# EOF

scitex/scholar/core/_mixins/_search.py

@@ -0,0 +1,103 @@
+#!/usr/bin/env python3
+# Timestamp: "2026-01-24 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-python/src/scitex/scholar/core/_mixins/_search.py
+
+"""
+Search mixin for Scholar class.
+
+Provides search functionality for local library and across projects.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, List, Optional
+
+from scitex import logging
+
+if TYPE_CHECKING:
+    from ..Papers import Papers
+
+logger = logging.getLogger(__name__)
+
+
+class SearchMixin:
+    """Mixin providing search methods."""
+
+    def search_library(self, query: str, project: Optional[str] = None) -> Papers:
+        """Search papers in local library.
+
+        For new literature search (not in library), use AI2 Scholar QA:
+        https://scholarqa.allen.ai/chat/ then process with:
+        papers = scholar.load_bibtex('file.bib') followed by scholar.enrich(papers)
+
+        Args:
+            query: Search query
+            project: Project filter (uses self.project if None)
+
+        Returns
+        -------
+            Papers collection matching the query
+        """
+        from ..Papers import Papers
+
+        logger.info(f"{self.name}: Searching library for: {query}")
+        return Papers([], project=project or self.project)
+
+    def search_across_projects(
+        self, query: str, projects: Optional[List[str]] = None
+    ) -> Papers:
+        """Search for papers across multiple projects or the entire library.
+
+        Args:
+            query: Search query
+            projects: List of project names to search (None for all)
+
+        Returns
+        -------
+            Papers collection with search results
+        """
+        from ..Paper import Paper
+        from ..Papers import Papers
+
+        if projects is None:
+            all_projects = [p["name"] for p in self.list_projects()]
+        else:
+            all_projects = projects
+
+        all_papers = []
+        for project in all_projects:
+            try:
+                project_dir = self.config.get_library_project_dir(project)
+                for item in project_dir.iterdir():
+                    if item.is_symlink() or item.is_dir():
+                        paper_dir = item.resolve() if item.is_symlink() else item
+                        metadata_file = paper_dir / "metadata.json"
+                        if metadata_file.exists():
+                            try:
+                                paper = Paper.model_validate_json(
+                                    metadata_file.read_text()
+                                )
+                                query_lower = query.lower()
+                                title = (paper.metadata.basic.title or "").lower()
+                                abstract = (paper.metadata.basic.abstract or "").lower()
+                                authors = paper.metadata.basic.authors or []
+                                if (
+                                    query_lower in title
+                                    or query_lower in abstract
+                                    or any(
+                                        query_lower in (a or "").lower()
+                                        for a in authors
+                                    )
+                                ):
+                                    all_papers.append(paper)
+                            except Exception as e:
+                                logger.debug(
+                                    f"{self.name}: Failed to load {metadata_file}: {e}"
+                                )
+            except Exception as e:
+                logger.debug(f"{self.name}: Failed to search project {project}: {e}")
+
+        return Papers(all_papers, config=self.config, project="search_results")
+
+
+# EOF

scitex/scholar/core/_mixins/_services.py

@@ -0,0 +1,88 @@
+#!/usr/bin/env python3
+# Timestamp: "2026-01-24 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-python/src/scitex/scholar/core/_mixins/_services.py
+
+"""
+Services mixin for Scholar class.
+
+Provides internal service properties with lazy loading.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from scitex.scholar.auth import ScholarAuthManager
+from scitex.scholar.browser import ScholarBrowserManager
+from scitex.scholar.config import ScholarConfig
+from scitex.scholar.metadata_engines.ScholarEngine import ScholarEngine
+from scitex.scholar.storage import LibraryManager, ScholarLibrary
+
+
+class ServiceMixin:
+    """Mixin providing internal service properties."""
+
+    def _init_config(self, config) -> ScholarConfig:
+        """Initialize configuration from various input types."""
+        if config is None:
+            return ScholarConfig.load()
+        elif isinstance(config, (str, Path)):
+            return ScholarConfig.from_yaml(config)
+        elif isinstance(config, ScholarConfig):
+            return config
+        else:
+            raise TypeError(f"Invalid config type: {type(config)}")
+
+    @property
+    def _scholar_engine(self) -> ScholarEngine:
+        """Get Scholar engine for search and enrichment (PRIVATE)."""
+        if not hasattr(self, "_ServiceMixin__scholar_engine"):
+            self.__scholar_engine = None
+        if self.__scholar_engine is None:
+            self.__scholar_engine = ScholarEngine(config=self.config)
+        return self.__scholar_engine
+
+    @property
+    def _auth_manager(self) -> ScholarAuthManager:
+        """Get authentication manager service (PRIVATE)."""
+        if not hasattr(self, "_ServiceMixin__auth_manager"):
+            self.__auth_manager = None
+        if self.__auth_manager is None:
+            self.__auth_manager = ScholarAuthManager()
+        return self.__auth_manager
+
+    @property
+    def _browser_manager(self) -> ScholarBrowserManager:
+        """Get browser manager service (PRIVATE)."""
+        if not hasattr(self, "_ServiceMixin__browser_manager"):
+            self.__browser_manager = None
+        if self.__browser_manager is None:
+            self.__browser_manager = ScholarBrowserManager(
+                auth_manager=self._auth_manager,
+                chrome_profile_name="system",
+                browser_mode=self.browser_mode,
+            )
+        return self.__browser_manager
+
+    @property
+    def _library_manager(self) -> LibraryManager:
+        """Get library manager service - low-level operations (PRIVATE)."""
+        if not hasattr(self, "_ServiceMixin__library_manager"):
+            self.__library_manager = None
+        if self.__library_manager is None:
+            self.__library_manager = LibraryManager(
+                project=self.project, config=self.config
+            )
+        return self.__library_manager
+
+    @property
+    def _library(self) -> ScholarLibrary:
+        """Get Scholar library service - high-level operations (PRIVATE)."""
+        if not hasattr(self, "_ServiceMixin__library"):
+            self.__library = None
+        if self.__library is None:
+            self.__library = ScholarLibrary(project=self.project, config=self.config)
+        return self.__library
+
+
+# EOF

scitex/scholar/core/_mixins/_url_finding.py

@@ -0,0 +1,105 @@
+#!/usr/bin/env python3
+# Timestamp: "2026-01-24 (ywatanabe)"
+# File: /home/ywatanabe/proj/scitex-python/src/scitex/scholar/core/_mixins/_url_finding.py
+
+"""
+URL finding mixin for Scholar class.
+
+Provides URL resolution and PDF URL discovery functionality.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List
+
+from scitex import logging
+
+logger = logging.getLogger(__name__)
+
+
+class URLFindingMixin:
+    """Mixin providing URL finding methods."""
+
+    async def _find_urls_for_doi_async(self, doi: str, context) -> Dict[str, Any]:
+        """Find all URLs for a DOI (orchestration layer).
+
+        Workflow:
+            DOI -> Publisher URL -> PDF URLs -> OpenURL (fallback)
+
+        Args:
+            doi: DOI string
+            context: Authenticated browser context
+
+        Returns
+        -------
+            Dictionary with URL information: {
+                "url_doi": "https://doi.org/...",
+                "url_publisher": "https://publisher.com/...",
+                "urls_pdf": [{"url": "...", "source": "zotero_translator"}],
+                "url_openurl_resolved": "..." (if fallback used)
+            }
+        """
+        from scitex.scholar.auth.gateway import (
+            OpenURLResolver,
+            normalize_doi_as_http,
+            resolve_publisher_url_by_navigating_to_doi_page,
+        )
+        from scitex.scholar.url_finder.ScholarURLFinder import ScholarURLFinder
+
+        urls = {"url_doi": normalize_doi_as_http(doi)}
+
+        # Step 1: Resolve publisher URL
+        page = await context.new_page()
+        try:
+            url_publisher = await resolve_publisher_url_by_navigating_to_doi_page(
+                doi, page
+            )
+            urls["url_publisher"] = url_publisher
+        finally:
+            await page.close()
+
+        # Step 2: Find PDF URLs from publisher URL
+        url_finder = ScholarURLFinder(context, config=self.config)
+        urls_pdf = []
+
+        if url_publisher:
+            urls_pdf = await url_finder.find_pdf_urls(url_publisher)
+
+        # Step 3: Try OpenURL fallback if no PDFs found
+        if not urls_pdf:
+            openurl_resolver = OpenURLResolver(config=self.config)
+            page = await context.new_page()
+            try:
+                url_openurl_resolved = await openurl_resolver.resolve_doi(doi, page)
+                urls["url_openurl_resolved"] = url_openurl_resolved
+
+                if url_openurl_resolved and url_openurl_resolved != "skipped":
+                    urls_pdf = await url_finder.find_pdf_urls(url_openurl_resolved)
+            finally:
+                await page.close()
+
+        urls["urls_pdf"] = self._deduplicate_pdf_urls(urls_pdf) if urls_pdf else []
+
+        return urls
+
+    def _deduplicate_pdf_urls(self, urls_pdf: List[Dict]) -> List[Dict]:
+        """Remove duplicate PDF URLs.
+
+        Args:
+            urls_pdf: List of PDF URL dicts
+
+        Returns
+        -------
+            Deduplicated list of PDF URL dicts
+        """
+        seen = set()
+        unique = []
+        for pdf in urls_pdf:
+            url = pdf.get("url") if isinstance(pdf, dict) else pdf
+            if url not in seen:
+                seen.add(url)
+                unique.append(pdf)
+        return unique
+
+
+# EOF

scitex/scholar/docs/EXTERNAL_PACKAGE_BRANDING.md

@@ -0,0 +1,149 @@
+# External Package Branding Guide
+
+When scitex wraps external packages (like `figrecipe` for `scitex.plt` or `crossref-local` for `scitex.scholar`), those packages should support configurable branding so documentation and error messages show the scitex namespace.
+
+## When to Use Branding
+
+- **Use branding**: External packages that scitex wraps (figrecipe, crossref-local, etc.)
+- **Don't use branding**: Internal scitex modules (scitex.audio, scitex.stats, etc.) - just hardcode `SCITEX_*` prefix
+
+## Pattern Overview
+
+The external package provides a `_branding.py` module that:
+1. Reads brand name from environment variable
+2. Derives environment variable prefix from brand name
+3. Provides helper functions for rebranding text/docstrings
+
+## Implementation Template
+
+```python
+# external_package/_branding.py
+
+import os
+import re
+from typing import Optional
+
+# Environment variables for branding
+# Parent package sets these before importing
+BRAND_NAME = os.environ.get("{PACKAGE}_BRAND", "{package}")
+BRAND_ALIAS = os.environ.get("{PACKAGE}_ALIAS", "{alias}")
+
+# Original values for replacement
+_ORIGINAL_NAME = "{package}"
+_ORIGINAL_ALIAS = "{alias}"
+
+
+def _brand_to_env_prefix(brand: str) -> str:
+    """Convert brand name to environment variable prefix.
+
+    Examples:
+        "figrecipe" -> "FIGRECIPE"
+        "scitex.plt" -> "SCITEX_PLT"
+        "crossref-local" -> "CROSSREF_LOCAL"
+    """
+    return brand.upper().replace(".", "_").replace("-", "_")
+
+
+# Environment variable prefix based on brand
+ENV_PREFIX = _brand_to_env_prefix(BRAND_NAME)
+
+
+def get_env(key: str, default: Optional[str] = None) -> Optional[str]:
+    """Get environment variable with brand-aware prefix.
+
+    Checks {ENV_PREFIX}_{key} first, then falls back to original prefix.
+    """
+    value = os.environ.get(f"{ENV_PREFIX}_{key}")
+    if value is not None:
+        return value
+
+    # Fall back to original prefix if different
+    original_prefix = _brand_to_env_prefix(_ORIGINAL_NAME)
+    if ENV_PREFIX != original_prefix:
+        value = os.environ.get(f"{original_prefix}_{key}")
+        if value is not None:
+            return value
+
+    return default
+
+
+def rebrand_text(text: Optional[str]) -> Optional[str]:
+    """Apply branding to a text string (docstrings, error messages)."""
+    if text is None:
+        return None
+
+    if BRAND_NAME == _ORIGINAL_NAME and BRAND_ALIAS == _ORIGINAL_ALIAS:
+        return text
+
+    result = text
+
+    # Replace import statements
+    result = re.sub(
+        rf"import\s+{_ORIGINAL_NAME}\s+as\s+{_ORIGINAL_ALIAS}",
+        f"import {BRAND_NAME} as {BRAND_ALIAS}",
+        result,
+    )
+
+    # Replace "from package" statements
+    result = re.sub(
+        rf"from\s+{_ORIGINAL_NAME}(\s+import|\s*\.)",
+        lambda m: f"from {BRAND_NAME}{m.group(1)}",
+        result,
+    )
+
+    return result
+
+
+def get_mcp_server_name() -> str:
+    """Get the MCP server name based on branding."""
+    return BRAND_NAME.replace(".", "-")
+```
+
+## Usage in Parent Package (scitex)
+
+```python
+# scitex/plt/__init__.py
+import os
+
+# Set branding BEFORE importing the external package
+os.environ["FIGRECIPE_BRAND"] = "scitex.plt"
+os.environ["FIGRECIPE_ALIAS"] = "plt"
+
+# Now import - docstrings will show scitex.plt instead of figrecipe
+from figrecipe import *
+```
+
+## Port Scheme
+
+SciTeX uses port scheme 3129X (TEX → te-ku-su → 2-9-3 in Japanese):
+
+| Port  | Service          |
+|-------|------------------|
+| 31290 | scitex-cloud     |
+| 31291 | crossref-local   |
+| 31292 | openalex         |
+| 31293 | scitex-audio     |
+
+## Environment Variable Pattern
+
+External packages should use `{ENV_PREFIX}_{SETTING}`:
+
+```
+SCITEX_PLT_MODE=local
+CROSSREF_LOCAL_API_URL=http://localhost:8333
+SCITEX_AUDIO_RELAY_URL=http://localhost:31293
+```
+
+## Example: crossref-local
+
+See GitHub Issue: https://github.com/ywatanabe1989/crossref-local/issues/11
+
+The crossref-local package should implement:
+- `CROSSREF_LOCAL_BRAND` / `CROSSREF_LOCAL_ALIAS` env vars
+- Dynamic `ENV_PREFIX` derived from brand name
+- When used via scitex.scholar, shows `scitex.scholar` in docs
+
+## References
+
+- figrecipe/_branding.py - Reference implementation
+- scitex/audio/_branding.py - Simple internal module (no rebranding needed)