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

scitex/scholar/crossref_scitex.py

@@ -0,0 +1,367 @@
+#!/usr/bin/env python3
+# Timestamp: 2026-01-24
+# File: src/scitex/scholar/crossref_scitex.py
+"""CrossRef-SciTeX: Local CrossRef database integration for scitex.scholar.
+
+This module provides access to the local CrossRef database (167M+ papers)
+through the crossref-local package. Branded as "crossref-scitex" to distinguish
+from the official CrossRef API. Supports both direct database access and HTTP
+API mode for remote servers.
+
+Quick Start
+-----------
+
+Search for papers:
+    >>> from scitex.scholar import crossref_scitex
+    >>> results = crossref_scitex.search("hippocampal sharp wave ripples")
+    >>> print(results.total, "papers found")
+
+Get paper by DOI:
+    >>> work = crossref_scitex.get("10.1126/science.aax0758")
+    >>> print(work.title)
+
+Configuration
+-------------
+
+The mode is automatically detected:
+- If CROSSREF_LOCAL_DB is set, uses direct database access
+- If CROSSREF_LOCAL_API_URL is set, uses HTTP API
+- Default: tries localhost:31291 (SciTeX port scheme)
+
+Environment variables (SCITEX_SCHOLAR_CROSSREF_* takes priority):
+    SCITEX_SCHOLAR_CROSSREF_DB: Path to local database
+    SCITEX_SCHOLAR_CROSSREF_MODE: 'db' or 'http'
+    CROSSREF_LOCAL_DB: Path to local database (fallback)
+    CROSSREF_LOCAL_API_URL: HTTP API URL (fallback)
+
+SSH tunnel for remote database:
+    $ ssh -L 31291:127.0.0.1:31291 your-server
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Optional
+
+# Set environment variables for crossref-local configuration
+# SCITEX_SCHOLAR_CROSSREF_* vars take priority in crossref-local's config.py
+
+if TYPE_CHECKING:
+    from crossref_local import SearchResult, Work
+    from crossref_local.citations import CitationNetwork
+
+__all__ = [
+    # Core search/retrieval
+    "search",
+    "count",
+    "get",
+    "get_many",
+    "exists",
+    # Enrichment
+    "enrich",
+    "enrich_dois",
+    # Configuration
+    "configure",
+    "configure_http",
+    "get_mode",
+    "info",
+    "is_available",
+    # Citation functions
+    "get_citing",
+    "get_cited",
+    "get_citation_count",
+    # Classes (re-exported)
+    "Work",
+    "SearchResult",
+    "CitationNetwork",
+    # Async API
+    "aio",
+    # Cache module
+    "cache",
+]
+
+
+def _ensure_crossref_local():
+    """Ensure crossref-local is available."""
+    try:
+        import crossref_local
+
+        return crossref_local
+    except ImportError as e:
+        raise ImportError(
+            "crossref-local not installed. Install with: pip install crossref-local"
+        ) from e
+
+
+def is_available() -> bool:
+    """Check if crossref-local is available and configured.
+
+    Returns
+    -------
+        True if crossref-local can be used (either DB or HTTP mode)
+    """
+    try:
+        crl = _ensure_crossref_local()
+        info_result = crl.info()
+        return info_result.get("status") == "ok"
+    except Exception:
+        return False
+
+
+# =============================================================================
+# Core Search/Retrieval Functions (delegated to crossref-local)
+# =============================================================================
+
+
+def search(
+    query: str,
+    limit: int = 20,
+    offset: int = 0,
+    **kwargs: Any,
+) -> SearchResult:
+    """Search for papers in the CrossRef database.
+
+    Args:
+        query: Search query string (full-text search)
+        limit: Maximum number of results (default: 20)
+        offset: Number of results to skip for pagination
+        **kwargs: Additional arguments passed to crossref-local
+
+    Returns
+    -------
+        SearchResult containing matching papers
+
+    Examples
+    --------
+        >>> from scitex.scholar import crossref
+        >>> results = crossref.search("deep learning")
+        >>> for work in results:
+        ...     print(work.title)
+    """
+    crl = _ensure_crossref_local()
+    return crl.search(query, limit=limit, offset=offset, **kwargs)
+
+
+def count(query: str) -> int:
+    """Count papers matching a search query.
+
+    Args:
+        query: Search query string
+
+    Returns
+    -------
+        Number of matching papers
+    """
+    crl = _ensure_crossref_local()
+    return crl.count(query)
+
+
+def get(doi: str) -> Optional[Work]:
+    """Get a paper by DOI.
+
+    Args:
+        doi: DOI of the paper (e.g., "10.1126/science.aax0758")
+
+    Returns
+    -------
+        Work object if found, None otherwise
+
+    Examples
+    --------
+        >>> work = crossref.get("10.1038/nature12373")
+        >>> if work:
+        ...     print(work.title, work.year)
+    """
+    crl = _ensure_crossref_local()
+    return crl.get(doi)
+
+
+def get_many(dois: list[str]) -> list[Work]:
+    """Get multiple papers by DOI.
+
+    Args:
+        dois: List of DOIs
+
+    Returns
+    -------
+        List of Work objects (None for DOIs not found)
+    """
+    crl = _ensure_crossref_local()
+    return crl.get_many(dois)
+
+
+def exists(doi: str) -> bool:
+    """Check if a DOI exists in the database.
+
+    Args:
+        doi: DOI to check
+
+    Returns
+    -------
+        True if DOI exists
+    """
+    crl = _ensure_crossref_local()
+    return crl.exists(doi)
+
+
+# =============================================================================
+# Enrichment Functions
+# =============================================================================
+
+
+def enrich(results: SearchResult) -> SearchResult:
+    """Enrich search results with citation data.
+
+    Args:
+        results: SearchResult to enrich
+
+    Returns
+    -------
+        Enriched SearchResult with citation counts and references
+    """
+    crl = _ensure_crossref_local()
+    return crl.enrich(results)
+
+
+def enrich_dois(dois: list[str]) -> list[Work]:
+    """Get and enrich papers by DOI with citation data.
+
+    Args:
+        dois: List of DOIs to enrich
+
+    Returns
+    -------
+        List of enriched Work objects
+    """
+    crl = _ensure_crossref_local()
+    return crl.enrich_dois(dois)
+
+
+# =============================================================================
+# Citation Functions
+# =============================================================================
+
+
+def get_citing(doi: str) -> list[str]:
+    """Get DOIs of papers that cite this paper.
+
+    Args:
+        doi: DOI of the paper
+
+    Returns
+    -------
+        List of DOIs that cite this paper
+    """
+    crl = _ensure_crossref_local()
+    return crl.get_citing(doi)
+
+
+def get_cited(doi: str) -> list[str]:
+    """Get DOIs of papers cited by this paper.
+
+    Args:
+        doi: DOI of the paper
+
+    Returns
+    -------
+        List of DOIs cited by this paper (references)
+    """
+    crl = _ensure_crossref_local()
+    return crl.get_cited(doi)
+
+
+def get_citation_count(doi: str) -> int:
+    """Get the citation count for a paper.
+
+    Args:
+        doi: DOI of the paper
+
+    Returns
+    -------
+        Number of citations
+    """
+    crl = _ensure_crossref_local()
+    return crl.get_citation_count(doi)
+
+
+# =============================================================================
+# Configuration Functions
+# =============================================================================
+
+
+def configure(db_path: str) -> None:
+    """Configure direct database access mode.
+
+    Args:
+        db_path: Path to the crossref.db file
+    """
+    crl = _ensure_crossref_local()
+    crl.configure(db_path)
+
+
+def configure_http(api_url: Optional[str] = None) -> None:
+    """Configure HTTP API mode.
+
+    Args:
+        api_url: API URL (default: http://localhost:31291)
+
+    Example:
+        >>> # After setting up SSH tunnel: ssh -L 31291:127.0.0.1:31291 server
+        >>> crossref.configure_http()
+    """
+    crl = _ensure_crossref_local()
+    crl.configure_http(api_url)
+
+
+def get_mode() -> str:
+    """Get the current operating mode.
+
+    Returns
+    -------
+        "db" for direct database access, "http" for API mode
+    """
+    crl = _ensure_crossref_local()
+    return crl.get_mode()
+
+
+def info() -> dict:
+    """Get information about the crossref-local configuration.
+
+    Returns
+    -------
+        Dict with status, mode, version, database stats, etc.
+    """
+    crl = _ensure_crossref_local()
+    return crl.info()
+
+
+# =============================================================================
+# Re-exported Classes and Modules
+# =============================================================================
+
+
+def __getattr__(name: str):
+    """Lazy import for classes and modules."""
+    if name == "Work":
+        from crossref_local import Work
+
+        return Work
+    elif name == "SearchResult":
+        from crossref_local import SearchResult
+
+        return SearchResult
+    elif name == "CitationNetwork":
+        from crossref_local.citations import CitationNetwork
+
+        return CitationNetwork
+    elif name == "aio":
+        from crossref_local import aio
+
+        return aio
+    elif name == "cache":
+        from crossref_local import cache
+
+        return cache
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+# 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 (sa-i-te-ku-su → 3-1-2-9 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:31291
+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)

scitex/scholar/examples/00_run_all.sh

@@ -0,0 +1,120 @@
+#!/bin/bash
+# -*- coding: utf-8 -*-
+# Timestamp: 2026-01-22
+# File: src/scitex/scholar/examples/00_run_all.sh
+# ----------------------------------------
+# Run all scholar examples in sequence
+# ----------------------------------------
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+usage() {
+    cat <<EOF
+Usage: $(basename "$0") [OPTIONS]
+
+Run all scholar module examples in sequence.
+
+Options:
+    -h, --help      Show this help message
+    --dry-run       Show commands without executing
+    --skip-auth     Skip authentication example (01_auth.py)
+    --quick         Run only quick examples (00, 01, 02)
+
+Examples:
+    $(basename "$0")              # Run all examples
+    $(basename "$0") --quick      # Run quick examples only
+    $(basename "$0") --dry-run    # Show what would run
+
+EOF
+    exit 0
+}
+
+DRY_RUN=false
+SKIP_AUTH=false
+QUICK=false
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+    -h | --help) usage ;;
+    --dry-run)
+        DRY_RUN=true
+        shift
+        ;;
+    --skip-auth)
+        SKIP_AUTH=true
+        shift
+        ;;
+    --quick)
+        QUICK=true
+        shift
+        ;;
+    *)
+        echo "Unknown option: $1"
+        usage
+        ;;
+    esac
+done
+
+run_example() {
+    local script="$1"
+    shift
+    local args=("$@")
+
+    if [[ ! -f "$SCRIPT_DIR/$script" ]]; then
+        echo "[SKIP] $script not found"
+        return 0
+    fi
+
+    echo ""
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo "Running: $script ${args[*]}"
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+    if [[ "$DRY_RUN" == "true" ]]; then
+        echo "[DRY-RUN] python $SCRIPT_DIR/$script ${args[*]}"
+    else
+        python "$SCRIPT_DIR/$script" "${args[@]}"
+    fi
+}
+
+echo "SciTeX Scholar Examples Runner"
+echo "==============================="
+
+# Core examples
+run_example "00_config.py"
+
+if [[ "$SKIP_AUTH" != "true" ]]; then
+    run_example "01_auth.py"
+fi
+
+run_example "02_browser.py"
+
+if [[ "$QUICK" == "true" ]]; then
+    echo ""
+    echo "Quick mode: Stopping after basic examples"
+    exit 0
+fi
+
+# Engine examples
+run_example "03_01-engine.py"
+run_example "03_02-engine-for-bibtex.py" --no-cache
+
+# URL finding examples
+run_example "04_01-url.py" --no-cache
+run_example "04_02-url-for-bibtex.py" --no-cache-url-finder --n-samples 3
+
+# Download examples
+run_example "05_download_pdf.py"
+run_example "06_find_and_download.py"
+
+# Storage integration
+run_example "07_storage_integration.py"
+
+echo ""
+echo "==============================="
+echo "All examples completed!"
+echo "==============================="
+
+# EOF

scitex/scholar/jobs/_executors.py

@@ -59,15 +59,39 @@ async def fetch_single_executor(
             force=force,
         )
 
+        # Granular success flags
+        has_doi = bool(paper and paper.metadata.id.doi)
+        has_metadata = bool(paper and paper.metadata.basic.title)
+        has_pdf = bool(symlink_path)
+        has_content = bool(
+            paper
+            and hasattr(paper, "container")
+            and paper.container.pdf_size_bytes
+            and paper.container.pdf_size_bytes > 0
+        )
+        pdf_method = None
+        if paper and paper.metadata.path.pdfs_engines:
+            pdf_method = paper.metadata.path.pdfs_engines[0]
+
         if progress_callback:
-            progress_callback(completed=1, message="Completed")
+            progress_callback(
+                completed=1, message="Completed" if has_pdf else "Completed (no PDF)"
+            )
 
         return {
-            "success": True,
+            "success": has_pdf,  # Overall success = PDF obtained
+            "success_doi": has_doi,
+            "success_metadata": has_metadata,
+            "success_pdf": has_pdf,
+            "success_content": has_content,
+            "pdf_method": pdf_method,
+            "message": "Paper fetched"
+            if has_pdf
+            else "Metadata fetched but PDF not downloaded",
             "doi": paper.metadata.id.doi if paper else None,
             "title": paper.metadata.basic.title if paper else None,
             "path": str(symlink_path) if symlink_path else None,
-            "has_pdf": bool(symlink_path),
+            "has_pdf": has_pdf,
             "timestamp": datetime.now().isoformat(),
         }