crossref-local 0.3.1__py3-none-any.whl → 0.5.0__py3-none-any.whl

crossref_local/{api.py → _core/api.py}

@@ -1,26 +1,45 @@
 """Main API for crossref_local.
 
 Supports two modes:
-- local: Direct database access (requires database file)
-- remote: HTTP API access (requires API server)
+- db: Direct database access (requires database file)
+- http: HTTP API access (requires API server)
 
 Mode is auto-detected or can be set explicitly via:
-- CROSSREF_LOCAL_MODE environment variable ("local" or "remote")
-- CROSSREF_LOCAL_API environment variable (API URL)
-- configure() or configure_remote() functions
+- CROSSREF_LOCAL_MODE environment variable ("db" or "http")
+- CROSSREF_LOCAL_API_URL environment variable (API URL)
+- configure() or configure_http() functions
 """
 
 from typing import List, Optional
 
-from .config import Config
-from .db import get_db, close_db
-from .models import Work, SearchResult
 from . import fts
-
-
-def _get_remote_client():
-    """Get remote client (lazy import to avoid circular dependency)."""
-    from .remote import RemoteClient
+from .config import Config
+from .db import close_db, get_db
+from .models import SearchResult, Work
+
+__all__ = [
+    "search",
+    "count",
+    "get",
+    "get_many",
+    "exists",
+    "configure",
+    "configure_http",
+    "configure_remote",
+    "enrich",
+    "enrich_dois",
+    "get_mode",
+    "info",
+    # Re-exported for convenience
+    "Work",
+    "SearchResult",
+    "Config",
+]
+
+
+def _get_http_client():
+    """Get HTTP client (lazy import to avoid circular dependency)."""
+    from .._remote import RemoteClient  # Uses enhanced client with collections
 
     return RemoteClient(Config.get_api_url())
 
@@ -48,9 +67,9 @@ def search(
         >>> results = search("machine learning")
         >>> print(f"Found {results.total} matches")
     """
-    if Config.get_mode() == "remote":
-        client = _get_remote_client()
-        return client.search(query=query, limit=limit)
+    if Config.get_mode() == "http":
+        client = _get_http_client()
+        return client.search(query=query, limit=limit, offset=offset)
     return fts.search(query, limit, offset)
 
 
@@ -64,8 +83,8 @@ def count(query: str) -> int:
     Returns:
         Number of matching works
     """
-    if Config.get_mode() == "remote":
-        client = _get_remote_client()
+    if Config.get_mode() == "http":
+        client = _get_http_client()
         result = client.search(query=query, limit=1)
         return result.total
     return fts.count(query)
@@ -86,8 +105,8 @@ def get(doi: str) -> Optional[Work]:
         >>> work = get("10.1038/nature12373")
         >>> print(work.title)
     """
-    if Config.get_mode() == "remote":
-        client = _get_remote_client()
+    if Config.get_mode() == "http":
+        client = _get_http_client()
         return client.get(doi)
     db = get_db()
     metadata = db.get_metadata(doi)
@@ -106,8 +125,8 @@ def get_many(dois: List[str]) -> List[Work]:
     Returns:
         List of Work objects (missing DOIs are skipped)
     """
-    if Config.get_mode() == "remote":
-        client = _get_remote_client()
+    if Config.get_mode() == "http":
+        client = _get_http_client()
         return client.get_many(dois)
     db = get_db()
     works = []
@@ -128,8 +147,8 @@ def exists(doi: str) -> bool:
     Returns:
         True if DOI exists
     """
-    if Config.get_mode() == "remote":
-        client = _get_remote_client()
+    if Config.get_mode() == "http":
+        client = _get_http_client()
         return client.exists(doi)
     db = get_db()
     row = db.fetchone("SELECT 1 FROM works WHERE doi = ?", (doi,))
@@ -151,29 +170,104 @@ def configure(db_path: str) -> None:
     close_db()  # Reset singleton to use new path
 
 
-def configure_remote(api_url: str = "http://localhost:3333") -> None:
+def configure_http(api_url: str = "http://localhost:8333") -> None:
     """
-    Configure for remote API access.
+    Configure for HTTP API access.
 
     Args:
         api_url: URL of CrossRef Local API server
 
     Example:
-        >>> from crossref_local import configure_remote
-        >>> configure_remote("http://localhost:3333")
+        >>> from crossref_local import configure_http
+        >>> configure_http("http://localhost:8333")
         >>> # Or via SSH tunnel:
-        >>> # ssh -L 3333:127.0.0.1:3333 nas
-        >>> configure_remote()  # Uses default localhost:3333
+        >>> # ssh -L 8333:127.0.0.1:8333 your-server
+        >>> configure_http()  # Uses default localhost:8333
     """
     Config.set_api_url(api_url)
 
 
+# Backward compatibility alias
+configure_remote = configure_http
+
+
+def enrich(
+    results: SearchResult,
+    include_citations: bool = True,
+    include_references: bool = True,
+) -> SearchResult:
+    """
+    Enrich search results with full metadata (citations, references).
+
+    The search() function returns basic metadata for speed. This function
+    fetches full metadata for each work, adding citation counts and references.
+
+    Args:
+        results: SearchResult from search()
+        include_citations: Include citation counts
+        include_references: Include reference DOIs
+
+    Returns:
+        SearchResult with enriched works
+
+    Example:
+        >>> from crossref_local import search, enrich
+        >>> results = search("machine learning", limit=10)
+        >>> enriched = enrich(results)
+        >>> for work in enriched:
+        ...     print(f"{work.title}: {work.citation_count} citations")
+    """
+    enriched_works = []
+    for work in results.works:
+        full_work = get(work.doi)
+        if full_work:
+            enriched_works.append(full_work)
+        else:
+            # Keep original if full metadata not available
+            enriched_works.append(work)
+
+    return SearchResult(
+        works=enriched_works,
+        total=results.total,
+        query=results.query,
+        elapsed_ms=results.elapsed_ms,
+    )
+
+
+def enrich_dois(
+    dois: List[str],
+    include_citations: bool = True,
+    include_references: bool = True,
+) -> List[Work]:
+    """
+    Enrich a list of DOIs with full metadata.
+
+    Fetches complete metadata for each DOI including citation counts
+    and reference lists.
+
+    Args:
+        dois: List of DOIs to enrich
+        include_citations: Include citation counts
+        include_references: Include reference DOIs
+
+    Returns:
+        List of Work objects with full metadata
+
+    Example:
+        >>> from crossref_local import enrich_dois
+        >>> works = enrich_dois(["10.1038/nature12373", "10.1126/science.aax0758"])
+        >>> for w in works:
+        ...     print(f"{w.doi}: {w.citation_count} citations, {len(w.references)} refs")
+    """
+    return get_many(dois)
+
+
 def get_mode() -> str:
     """
     Get current mode.
 
     Returns:
-        "local" or "remote"
+        "db" or "http"
     """
     return Config.get_mode()
 
@@ -187,10 +281,10 @@ def info() -> dict:
     """
     mode = Config.get_mode()
 
-    if mode == "remote":
-        client = _get_remote_client()
-        remote_info = client.info()
-        return {"mode": "remote", **remote_info}
+    if mode == "http":
+        client = _get_http_client()
+        http_info = client.info()
+        return {"mode": "http", **http_info}
 
     db = get_db()
 
@@ -213,7 +307,7 @@ def info() -> dict:
         citation_count = 0
 
     return {
-        "mode": "local",
+        "mode": "db",
         "db_path": str(Config.get_db_path()),
         "works": work_count,
         "fts_indexed": fts_count,

crossref_local/{citations.py → _core/citations.py}

@@ -16,13 +16,22 @@ Usage:
     network.save_html("citation_network.html")
 """
 
-from dataclasses import dataclass, field
-from typing import List, Dict, Optional, Set, Tuple
-from pathlib import Path
+from dataclasses import dataclass as _dataclass
+from dataclasses import field as _field
+from typing import Dict, List, Optional, Set, Tuple
 
-from .db import get_db, Database
+from .db import Database, get_db
 from .models import Work
 
+__all__ = [
+    "get_citing",
+    "get_cited",
+    "get_citation_count",
+    "CitationNode",
+    "CitationEdge",
+    "CitationNetwork",
+]
+
 
 def get_citing(doi: str, limit: int = 100, db: Optional[Database] = None) -> List[str]:
     """
@@ -46,7 +55,7 @@ def get_citing(doi: str, limit: int = 100, db: Optional[Database] = None) -> Lis
         WHERE cited_doi = ?
         LIMIT ?
         """,
-        (doi, limit)
+        (doi, limit),
     )
     return [row["citing_doi"] for row in rows]
 
@@ -73,7 +82,7 @@ def get_cited(doi: str, limit: int = 100, db: Optional[Database] = None) -> List
         WHERE citing_doi = ?
         LIMIT ?
         """,
-        (doi, limit)
+        (doi, limit),
     )
     return [row["cited_doi"] for row in rows]
 
@@ -93,18 +102,18 @@ def get_citation_count(doi: str, db: Optional[Database] = None) -> int:
         db = get_db()
 
     row = db.fetchone(
-        "SELECT COUNT(*) as count FROM citations WHERE cited_doi = ?",
-        (doi,)
+        "SELECT COUNT(*) as count FROM citations WHERE cited_doi = ?", (doi,)
     )
     return row["count"] if row else 0
 
 
-@dataclass
+@_dataclass
 class CitationNode:
     """A node in the citation network."""
+
     doi: str
     title: str = ""
-    authors: List[str] = field(default_factory=list)
+    authors: List[str] = _field(default_factory=list)
     year: Optional[int] = None
     journal: str = ""
     citation_count: int = 0
@@ -122,9 +131,10 @@ class CitationNode:
         }
 
 
-@dataclass
+@_dataclass
 class CitationEdge:
     """An edge in the citation network (citing -> cited)."""
+
     citing_doi: str
     cited_doi: str
     year: Optional[int] = None
@@ -272,6 +282,8 @@ class CitationNetwork:
         Raises:
             ImportError: If pyvis is not installed
         """
+        import math as _math
+
         try:
             from pyvis.network import Network
         except ImportError:
@@ -284,7 +296,7 @@ class CitationNetwork:
             directed=True,
             bgcolor="#ffffff",
             font_color="#333333",
-            **kwargs
+            **kwargs,
         )
 
         # Configure physics
@@ -298,15 +310,16 @@ class CitationNetwork:
         # Add nodes with styling based on depth and citation count
         for doi, node in self.nodes.items():
             # Size based on citation count (log scale)
-            import math
-            size = 10 + min(30, math.log1p(node.citation_count) * 5)
+            size = 10 + min(30, _math.log1p(node.citation_count) * 5)
 
             # Color based on depth
             colors = ["#e74c3c", "#3498db", "#2ecc71", "#9b59b6", "#f39c12"]
             color = colors[min(node.depth, len(colors) - 1)]
 
             # Label
-            title_short = (node.title[:50] + "...") if len(node.title) > 50 else node.title
+            title_short = (
+                (node.title[:50] + "...") if len(node.title) > 50 else node.title
+            )
             label = f"{title_short}\n({node.year or 'N/A'})"
 
             # Tooltip
@@ -316,7 +329,7 @@ class CitationNetwork:
             tooltip = f"""
             <b>{node.title}</b><br>
             {authors_str}<br>
-            {node.journal} ({node.year or 'N/A'})<br>
+            {node.journal} ({node.year or "N/A"})<br>
             Citations: {node.citation_count}<br>
             DOI: {doi}
             """
@@ -340,7 +353,9 @@ class CitationNetwork:
         net.save_graph(path)
         return path
 
-    def save_png(self, path: str = "citation_network.png", figsize: Tuple[int, int] = (12, 10)):
+    def save_png(
+        self, path: str = "citation_network.png", figsize: Tuple[int, int] = (12, 10)
+    ):
         """
         Save static PNG visualization using matplotlib.
 
@@ -351,6 +366,8 @@ class CitationNetwork:
         Raises:
             ImportError: If matplotlib is not installed
         """
+        import math as _math
+
         try:
             import matplotlib.pyplot as plt
             import networkx as nx
@@ -365,24 +382,34 @@ class CitationNetwork:
         pos = nx.spring_layout(G, k=2, iterations=50)
 
         # Node sizes based on citation count
-        import math
-        sizes = [100 + min(500, math.log1p(self.nodes[n].citation_count) * 50) for n in G.nodes()]
+        sizes = [
+            100 + min(500, _math.log1p(self.nodes[n].citation_count) * 50)
+            for n in G.nodes()
+        ]
 
         # Node colors based on depth
         colors = [self.nodes[n].depth for n in G.nodes()]
 
         # Draw
-        nx.draw_networkx_nodes(G, pos, node_size=sizes, node_color=colors,
-                               cmap=plt.cm.RdYlBu_r, alpha=0.8, ax=ax)
-        nx.draw_networkx_edges(G, pos, alpha=0.3, arrows=True,
-                               arrowsize=10, ax=ax)
+        nx.draw_networkx_nodes(
+            G,
+            pos,
+            node_size=sizes,
+            node_color=colors,
+            cmap=plt.cm.RdYlBu_r,
+            alpha=0.8,
+            ax=ax,
+        )
+        nx.draw_networkx_edges(G, pos, alpha=0.3, arrows=True, arrowsize=10, ax=ax)
 
         # Labels for important nodes (high citation count)
         labels = {}
         for doi in G.nodes():
             node = self.nodes[doi]
             if node.citation_count > 10 or doi == self.center_doi:
-                short_title = (node.title[:30] + "...") if len(node.title) > 30 else node.title
+                short_title = (
+                    (node.title[:30] + "...") if len(node.title) > 30 else node.title
+                )
                 labels[doi] = f"{short_title}\n({node.year or 'N/A'})"
 
         nx.draw_networkx_labels(G, pos, labels, font_size=8, ax=ax)
@@ -402,11 +429,13 @@ class CitationNetwork:
             "center_doi": self.center_doi,
             "depth": self.depth,
             "nodes": [n.to_dict() for n in self.nodes.values()],
-            "edges": [{"citing": e.citing_doi, "cited": e.cited_doi} for e in self.edges],
+            "edges": [
+                {"citing": e.citing_doi, "cited": e.cited_doi} for e in self.edges
+            ],
             "stats": {
                 "total_nodes": len(self.nodes),
                 "total_edges": len(self.edges),
-            }
+            },
         }
 
     def __repr__(self):

crossref_local/{config.py → _core/config.py}

@@ -1,32 +1,42 @@
 """Configuration for crossref_local."""
 
-import os
-from pathlib import Path
+import os as _os
+from pathlib import Path as _Path
 from typing import Optional
 
+__all__ = [
+    "Config",
+    "get_db_path",
+    "DEFAULT_PORT",
+    "DEFAULT_API_URL",
+]
+
 # Default database locations (checked in order)
 DEFAULT_DB_PATHS = [
-    Path("/home/ywatanabe/proj/crossref-local/data/crossref.db"),
-    Path("/home/ywatanabe/proj/crossref_local/data/crossref.db"),
-    Path("/mnt/nas_ug/crossref_local/data/crossref.db"),
-    Path.home() / ".crossref_local" / "crossref.db",
-    Path.cwd() / "data" / "crossref.db",
+    _Path.cwd() / "data" / "crossref.db",
+    _Path.home() / ".crossref_local" / "crossref.db",
 ]
 
-# Default remote API URL (via SSH tunnel)
+# Default port: SCITEX convention (3129X scheme)
+# 31290: scitex-cloud, 31291: crossref-local, 31292: openalex-local, 31293: audio relay
+DEFAULT_PORT = 31291
+
+# Default remote API URLs (checked in order)
 DEFAULT_API_URLS = [
-    "http://localhost:3333",  # SSH tunnel to NAS
+    f"http://localhost:{DEFAULT_PORT}",  # SCITEX default
+    "http://localhost:8333",  # Legacy port (backwards compatibility)
 ]
 DEFAULT_API_URL = DEFAULT_API_URLS[0]
 
 
-def get_db_path() -> Path:
+def get_db_path() -> _Path:
     """
     Get database path from environment or auto-detect.
 
     Priority:
-    1. CROSSREF_LOCAL_DB environment variable
-    2. First existing path from DEFAULT_DB_PATHS
+    1. SCITEX_SCHOLAR_CROSSREF_DB environment variable
+    2. CROSSREF_LOCAL_DB environment variable
+    3. First existing path from DEFAULT_DB_PATHS
 
     Returns:
         Path to the database file
@@ -34,13 +44,15 @@ def get_db_path() -> Path:
     Raises:
         FileNotFoundError: If no database found
     """
-    # Check environment variable first
-    env_path = os.environ.get("CROSSREF_LOCAL_DB")
+    # Check SCITEX environment variable first (takes priority)
+    env_path = _os.environ.get("SCITEX_SCHOLAR_CROSSREF_DB")
+    if not env_path:
+        env_path = _os.environ.get("CROSSREF_LOCAL_DB")
     if env_path:
-        path = Path(env_path)
+        path = _Path(env_path)
         if path.exists():
             return path
-        raise FileNotFoundError(f"CROSSREF_LOCAL_DB path not found: {env_path}")
+        raise FileNotFoundError(f"Database path not found: {env_path}")
 
     # Auto-detect from default locations
     for path in DEFAULT_DB_PATHS:
@@ -56,9 +68,9 @@ def get_db_path() -> Path:
 class Config:
     """Configuration container."""
 
-    _db_path: Optional[Path] = None
+    _db_path: Optional[_Path] = None
     _api_url: Optional[str] = None
-    _mode: str = "auto"  # "auto", "local", or "remote"
+    _mode: str = "auto"  # "auto", "db", or "http"
 
     @classmethod
     def get_mode(cls) -> str:
@@ -66,53 +78,56 @@ class Config:
         Get current mode.
 
         Returns:
-            "local" if using direct database access
-            "remote" if using HTTP API
+            "db" if using direct database access
+            "http" if using HTTP API
         """
         if cls._mode == "auto":
-            # Check environment variable
-            env_mode = os.environ.get("CROSSREF_LOCAL_MODE", "").lower()
-            if env_mode in ("remote", "api"):
-                return "remote"
-            if env_mode == "local":
-                return "local"
+            # Check environment variables (SCITEX takes priority)
+            env_mode = _os.environ.get(
+                "SCITEX_SCHOLAR_CROSSREF_MODE",
+                _os.environ.get("CROSSREF_LOCAL_MODE", ""),
+            ).lower()
+            if env_mode in ("http", "remote", "api"):
+                return "http"
+            if env_mode in ("db", "local"):
+                return "db"
 
             # Check if API URL is set
-            if cls._api_url or os.environ.get("CROSSREF_LOCAL_API"):
-                return "remote"
+            if cls._api_url or _os.environ.get("CROSSREF_LOCAL_API_URL"):
+                return "http"
 
             # Check if local database exists
             try:
                 get_db_path()
-                return "local"
+                return "db"
             except FileNotFoundError:
-                # No local DB, try remote
-                return "remote"
+                # No local DB, try http
+                return "http"
 
         return cls._mode
 
     @classmethod
     def set_mode(cls, mode: str) -> None:
-        """Set mode explicitly: 'local', 'remote', or 'auto'."""
-        if mode not in ("auto", "local", "remote"):
-            raise ValueError(f"Invalid mode: {mode}. Use 'auto', 'local', or 'remote'")
+        """Set mode explicitly: 'db', 'http', or 'auto'."""
+        if mode not in ("auto", "db", "http"):
+            raise ValueError(f"Invalid mode: {mode}. Use 'auto', 'db', or 'http'")
         cls._mode = mode
 
     @classmethod
-    def get_db_path(cls) -> Path:
+    def get_db_path(cls) -> _Path:
         """Get or auto-detect database path."""
         if cls._db_path is None:
             cls._db_path = get_db_path()
         return cls._db_path
 
     @classmethod
-    def set_db_path(cls, path: str | Path) -> None:
+    def set_db_path(cls, path: str | _Path) -> None:
         """Set database path explicitly."""
-        path = Path(path)
+        path = _Path(path)
         if not path.exists():
             raise FileNotFoundError(f"Database not found: {path}")
         cls._db_path = path
-        cls._mode = "local"
+        cls._mode = "db"
 
     @classmethod
     def get_api_url(cls, auto_detect: bool = True) -> str:
@@ -128,7 +143,7 @@ class Config:
         if cls._api_url:
             return cls._api_url
 
-        env_url = os.environ.get("CROSSREF_LOCAL_API")
+        env_url = _os.environ.get("CROSSREF_LOCAL_API_URL")
         if env_url:
             return env_url
 
@@ -143,8 +158,8 @@ class Config:
     @classmethod
     def _find_working_api(cls) -> Optional[str]:
         """Try each default API URL and return first working one."""
-        import urllib.request
         import urllib.error
+        import urllib.request
 
         for url in DEFAULT_API_URLS:
             try:
@@ -159,9 +174,9 @@ class Config:
 
     @classmethod
     def set_api_url(cls, url: str) -> None:
-        """Set API URL for remote mode."""
+        """Set API URL for http mode."""
         cls._api_url = url.rstrip("/")
-        cls._mode = "remote"
+        cls._mode = "http"
 
     @classmethod
     def reset(cls) -> None: