scitex 2.4.1__py3-none-any.whl → 2.4.3__py3-none-any.whl

scitex/scholar/citation_graph/models.py

@@ -0,0 +1,80 @@
+"""
+Data models for citation graphs.
+"""
+
+from dataclasses import dataclass, field
+from typing import List, Dict, Optional
+
+
+@dataclass
+class PaperNode:
+    """Represents a paper in the citation network."""
+
+    doi: str
+    title: str = ""
+    year: int = 0
+    authors: List[str] = field(default_factory=list)
+    journal: str = ""
+    citation_count: int = 0
+    similarity_score: float = 0.0
+    metadata: Dict = field(default_factory=dict)
+
+    def to_dict(self) -> Dict:
+        """Convert to dictionary for JSON export."""
+        return {
+            "id": self.doi,
+            "title": self.title,
+            "year": self.year,
+            "authors": self.authors,
+            "journal": self.journal,
+            "citation_count": self.citation_count,
+            "similarity_score": self.similarity_score,
+        }
+
+
+@dataclass
+class CitationEdge:
+    """Represents a citation relationship between papers."""
+
+    source: str  # DOI of citing paper
+    target: str  # DOI of cited paper
+    edge_type: str = "cites"  # 'cites', 'cited_by', 'similar'
+    weight: float = 1.0
+
+    def to_dict(self) -> Dict:
+        """Convert to dictionary for JSON export."""
+        return {
+            "source": self.source,
+            "target": self.target,
+            "type": self.edge_type,
+            "weight": self.weight,
+        }
+
+
+@dataclass
+class CitationGraph:
+    """Represents a complete citation network."""
+
+    seed_doi: str
+    nodes: List[PaperNode] = field(default_factory=list)
+    edges: List[CitationEdge] = field(default_factory=list)
+    metadata: Dict = field(default_factory=dict)
+
+    def to_dict(self) -> Dict:
+        """Convert to dictionary for JSON export."""
+        return {
+            "seed": self.seed_doi,
+            "nodes": [node.to_dict() for node in self.nodes],
+            "edges": [edge.to_dict() for edge in self.edges],
+            "metadata": self.metadata,
+        }
+
+    @property
+    def node_count(self) -> int:
+        """Number of nodes in graph."""
+        return len(self.nodes)
+
+    @property
+    def edge_count(self) -> int:
+        """Number of edges in graph."""
+        return len(self.edges)

scitex/scholar/config/ScholarConfig.py

@@ -29,8 +29,22 @@ logger = getLogger(__name__)
 
 
 class ScholarConfig:
-    def __init__(self, config_path: Optional[Union[str, Path]] = None):
+    def __init__(
+        self,
+        config_path: Optional[Union[str, Path]] = None,
+        scholar_dir: Optional[Union[str, Path]] = None,
+    ):
+        """Initialize ScholarConfig.
+
+        Args:
+            config_path: Path to custom config YAML file
+            scholar_dir: Direct path to scholar directory (e.g., /data/users/alice/.scitex)
+                        This bypasses SCITEX_DIR env var for thread-safe multi-user usage.
+                        Use this in Django/multi-user environments to avoid race conditions.
+        """
         self.name = self.__class__.__name__
+        self._explicit_scholar_dir = scholar_dir  # Store for thread-safe access
+
         if config_path and Path(config_path).exists():
             config_data = self.load_yaml(config_path)
         else:
@@ -114,8 +128,14 @@ class ScholarConfig:
 
     # Path Management ----------------------------------------
     def _setup_path_manager(self, scholar_dir=None):
-        scholar_dir = self.cascade.resolve("scholar_dir", default="~/.scitex")
-        base_path = Path(scholar_dir).expanduser() / "scholar"
+        # Priority: explicit parameter > env var > config > default
+        if self._explicit_scholar_dir:
+            # Use explicitly provided path (thread-safe for multi-user)
+            base_path = Path(self._explicit_scholar_dir).expanduser() / "scholar"
+        else:
+            # Fall back to cascade resolution (uses SCITEX_DIR env var)
+            scholar_dir = self.cascade.resolve("scholar_dir", default="~/.scitex")
+            base_path = Path(scholar_dir).expanduser() / "scholar"
         self.path_manager = PathManager(scholar_dir=base_path)
 
     @property

scitex/scholar/config/default.yaml

@@ -38,6 +38,61 @@ timeout: 60
 # Note: Download directory is fixed at {scholar_dir}/library/downloads/
 # Use get_library_downloads_dir() to access it
 
+# Open Access & Paywall Options
+# ----------------------------------------
+# Prefer Open Access versions when available
+prefer_open_access: ${SCITEX_SCHOLAR_PREFER_OPEN_ACCESS:-true}
+# Allow attempting paywalled journal downloads (requires authentication)
+# Only enable for local/personal use with valid institutional access
+enable_paywall_access: ${SCITEX_SCHOLAR_ENABLE_PAYWALL_ACCESS:-false}
+# Track paywall bypass attempts in metadata (for transparency)
+track_paywall_attempts: ${SCITEX_SCHOLAR_TRACK_PAYWALL_ATTEMPTS:-true}
+
+# Open Access Sources (repositories that are always free to download)
+OPENACCESS_SOURCES:
+  - arxiv
+  - pmc
+  - pubmed_central
+  - biorxiv
+  - medrxiv
+  - chemrxiv
+  - doaj
+  - plos
+  - peerj
+  - frontiers
+  - mdpi
+  - hindawi
+  - nature_communications  # Most articles are OA
+
+# Open Access Journals (partial list, DOAJ has full list)
+# These are journal name patterns (case-insensitive substring match)
+OPENACCESS_JOURNALS:
+  - "plos one"
+  - "plos biology"
+  - "plos medicine"
+  - "plos computational biology"
+  - "plos genetics"
+  - "plos pathogens"
+  - "plos neglected tropical diseases"
+  - "scientific reports"
+  - "nature communications"
+  - "elife"
+  - "peerj"
+  - "frontiers in"  # All Frontiers journals
+  - "bmc "          # All BMC journals
+  - "journal of open source software"
+  - "f1000research"
+  - "gigascience"
+  - "cell reports"
+  - "science advances"
+  - "iscience"
+  - "heliyon"
+  - "cureus"
+  - "jmir"          # Journal of Medical Internet Research
+
+# Unpaywall API email (required for polite access)
+unpaywall_email: ${SCITEX_SCHOLAR_UNPAYWALL_EMAIL:-"research@scitex.io"}
+
 # ----------------------------------------
 # cache
 # ----------------------------------------
@@ -54,6 +109,7 @@ timeout: 60
 # ----------------------------------------
 semantic_scholar_api_key: ${SCITEX_SCHOLAR_SEMANTIC_SCHOLAR_API_KEY:-null}
 crossref_api_key: ${SCITEX_SCHOLAR_CROSSREF_API_KEY:-null}
+crossref_api_url: ${SCITEX_SCHOLAR_CROSSREF_API_URL:-"http://127.0.0.1:3333"}
 pubmed_api_key: ${SCITEX_SCHOLAR_PUBMED_API_KEY:-null}
 twocaptcha_api_key: ${SCITEX_SCHOLAR_2CAPTCHA_API_KEY:-null}
 

scitex/scholar/core/Paper.py

@@ -284,6 +284,37 @@ class PathMetadata(BaseModel):
         validate_assignment = True  # Validate on attribute assignment too
 
 
+class AccessMetadata(BaseModel):
+    """Open access and licensing metadata with source tracking.
+
+    Tracks whether a paper is open access and provides URLs for OA versions.
+    Also includes license information when available.
+    """
+
+    is_open_access: Optional[bool] = None
+    is_open_access_engines: List[str] = Field(default_factory=list)
+
+    oa_status: Optional[str] = None  # gold, green, bronze, hybrid, closed
+    oa_status_engines: List[str] = Field(default_factory=list)
+
+    oa_url: Optional[str] = None  # URL to open access version
+    oa_url_engines: List[str] = Field(default_factory=list)
+
+    license: Optional[str] = None  # CC-BY, CC-BY-NC, etc.
+    license_engines: List[str] = Field(default_factory=list)
+
+    license_url: Optional[str] = None
+    license_url_engines: List[str] = Field(default_factory=list)
+
+    # For paywalled journals - opt-in for local/personal users
+    paywall_bypass_attempted: Optional[bool] = None
+    paywall_bypass_success: Optional[bool] = None
+
+    class Config:
+        populate_by_name = True
+        validate_assignment = True
+
+
 class SystemMetadata(BaseModel):
     """System tracking metadata (which engines were used to search)."""
 
@@ -313,6 +344,7 @@ class PaperMetadataStructure(BaseModel):
     )
     url: URLMetadata = Field(default_factory=URLMetadata)
     path: PathMetadata = Field(default_factory=PathMetadata)
+    access: AccessMetadata = Field(default_factory=AccessMetadata)
     system: SystemMetadata = Field(default_factory=SystemMetadata)
 
     class Config:
@@ -418,6 +450,7 @@ class PaperMetadataStructure(BaseModel):
             ),
             "url": self.url.model_dump(by_alias=True, **kwargs),
             "path": self.path.model_dump(by_alias=True, **kwargs),
+            "access": self.access.model_dump(by_alias=True, **kwargs),
             "system": self.system.model_dump(by_alias=True, **kwargs),
         }
 
@@ -489,6 +522,75 @@ class Paper(BaseModel):
         """
         return self.model_dump()
 
+    def detect_open_access(
+        self,
+        use_unpaywall: bool = False,
+        update_metadata: bool = True,
+    ) -> "OAResult":
+        """
+        Detect open access status for this paper.
+
+        Uses identifiers (DOI, arXiv ID, PMCID) and known OA sources
+        to determine if the paper is freely available.
+
+        Args:
+            use_unpaywall: If True, query Unpaywall API for uncertain cases
+            update_metadata: If True, update self.metadata.access with results
+
+        Returns:
+            OAResult with detection results
+        """
+        from .open_access import check_oa_status, OAResult
+
+        result = check_oa_status(
+            doi=self.metadata.id.doi,
+            arxiv_id=self.metadata.id.arxiv_id,
+            pmcid=None,  # Not currently in IDMetadata
+            source=None,  # Source tracking not in Paper
+            journal=self.metadata.publication.journal,
+            is_open_access_flag=self.metadata.access.is_open_access,
+            use_unpaywall=use_unpaywall,
+        )
+
+        if update_metadata:
+            self.metadata.access.is_open_access = result.is_open_access
+            self.metadata.access.is_open_access_engines.append(
+                f"detect_oa:{result.source}"
+            )
+            if result.status:
+                self.metadata.access.oa_status = result.status.value
+                self.metadata.access.oa_status_engines.append(
+                    f"detect_oa:{result.source}"
+                )
+            if result.oa_url:
+                self.metadata.access.oa_url = result.oa_url
+                self.metadata.access.oa_url_engines.append(
+                    f"detect_oa:{result.source}"
+                )
+            if result.license:
+                self.metadata.access.license = result.license
+                self.metadata.access.license_engines.append(
+                    f"detect_oa:{result.source}"
+                )
+
+        return result
+
+    @property
+    def is_open_access(self) -> bool:
+        """Check if paper is open access (quick check without API calls)."""
+        if self.metadata.access.is_open_access is not None:
+            return self.metadata.access.is_open_access
+
+        # Quick detection from identifiers
+        from .open_access import detect_oa_from_identifiers
+
+        result = detect_oa_from_identifiers(
+            doi=self.metadata.id.doi,
+            arxiv_id=self.metadata.id.arxiv_id,
+            journal=self.metadata.publication.journal,
+        )
+        return result.is_open_access
+
 
 if __name__ == "__main__":
     import json

scitex/scholar/core/__init__.py

@@ -1,9 +1,53 @@
 from .Paper import Paper
 from .Papers import Papers
 from .Scholar import Scholar
+from .open_access import (
+    OAStatus,
+    OAResult,
+    detect_oa_from_identifiers,
+    check_oa_status,
+    check_oa_status_async,
+    is_open_access_source,
+    is_open_access_journal,
+    is_arxiv_id,
+)
+from .oa_cache import (
+    OASourcesCache,
+    get_oa_cache,
+    is_oa_journal_cached,
+    refresh_oa_cache,
+)
+from .journal_normalizer import (
+    JournalNormalizer,
+    get_journal_normalizer,
+    normalize_journal_name,
+    get_journal_issn_l,
+    is_same_journal,
+    refresh_journal_cache,
+)
 
 __all__ = [
     "Paper",
     "Papers",
     "Scholar",
+    "OAStatus",
+    "OAResult",
+    "detect_oa_from_identifiers",
+    "check_oa_status",
+    "check_oa_status_async",
+    "is_open_access_source",
+    "is_open_access_journal",
+    "is_arxiv_id",
+    # OA Cache
+    "OASourcesCache",
+    "get_oa_cache",
+    "is_oa_journal_cached",
+    "refresh_oa_cache",
+    # Journal Normalizer
+    "JournalNormalizer",
+    "get_journal_normalizer",
+    "normalize_journal_name",
+    "get_journal_issn_l",
+    "is_same_journal",
+    "refresh_journal_cache",
 ]