openalex-local 0.1.0__py3-none-any.whl → 0.3.1__py3-none-any.whl

openalex_local/_core/api.py

@@ -0,0 +1,376 @@
+"""Main API for openalex_local.
+
+Supports two modes:
+- db: Direct database access (requires database file)
+- http: HTTP API access (requires API server)
+
+Mode is auto-detected or can be set explicitly via:
+- OPENALEX_LOCAL_MODE environment variable ("db" or "http")
+- OPENALEX_LOCAL_API_URL environment variable (API URL)
+- configure() or configure_http() functions
+"""
+
+from typing import List, Optional
+
+from . import fts
+from .config import Config
+from .db import close_db, get_db
+from .models import SearchResult, Work
+
+__all__ = [
+    # Core functions
+    "search",
+    "count",
+    "get",
+    "get_many",
+    "exists",
+    "info",
+    # Enrich functions
+    "enrich",
+    "enrich_ids",
+    # Configuration
+    "configure",
+    "get_mode",
+    # Models (public)
+    "Work",
+    "SearchResult",
+]
+
+
+def _get_http_client():
+    """Get HTTP client (lazy import to avoid circular dependency)."""
+    from .._remote import RemoteClient
+
+    return RemoteClient(Config.get_api_url())
+
+
+def search(
+    query: str,
+    limit: int = 20,
+    offset: int = 0,
+) -> SearchResult:
+    """
+    Full-text search across works.
+
+    Uses FTS5 index for fast searching across titles and abstracts.
+
+    Args:
+        query: Search query (supports FTS5 syntax)
+        limit: Maximum results to return
+        offset: Skip first N results (for pagination)
+
+    Returns:
+        SearchResult with matching works
+
+    Example:
+        >>> from openalex_local import search
+        >>> results = search("machine learning")
+        >>> print(f"Found {results.total} matches")
+    """
+    if Config.get_mode() == "http":
+        client = _get_http_client()
+        return client.search(query=query, limit=limit, offset=offset)
+    return fts.search(query, limit, offset)
+
+
+def count(query: str) -> int:
+    """
+    Count matching works without fetching results.
+
+    Args:
+        query: FTS5 search query
+
+    Returns:
+        Number of matching works
+    """
+    if Config.get_mode() == "http":
+        client = _get_http_client()
+        result = client.search(query=query, limit=1)
+        return result.total
+    return fts.count(query)
+
+
+def get(id_or_doi: str) -> Optional[Work]:
+    """
+    Get a work by OpenAlex ID or DOI.
+
+    Args:
+        id_or_doi: OpenAlex ID (e.g., W2741809807) or DOI
+
+    Returns:
+        Work object or None if not found
+
+    Example:
+        >>> from openalex_local import get
+        >>> work = get("W2741809807")
+        >>> work = get("10.1038/nature12373")
+        >>> print(work.title)
+    """
+    if Config.get_mode() == "http":
+        client = _get_http_client()
+        return client.get(id_or_doi)
+
+    db = get_db()
+
+    # Try as OpenAlex ID first
+    if id_or_doi.startswith("W") or id_or_doi.startswith("w"):
+        data = db.get_work(id_or_doi.upper())
+        if data:
+            return Work.from_db_row(data)
+
+    # Try as DOI
+    data = db.get_work_by_doi(id_or_doi)
+    if data:
+        return Work.from_db_row(data)
+
+    return None
+
+
+def get_many(ids: List[str]) -> List[Work]:
+    """
+    Get multiple works by OpenAlex ID or DOI.
+
+    Args:
+        ids: List of OpenAlex IDs or DOIs
+
+    Returns:
+        List of Work objects (missing IDs are skipped)
+    """
+    if Config.get_mode() == "http":
+        client = _get_http_client()
+        return client.get_many(ids)
+
+    works = []
+    for id_or_doi in ids:
+        work = get(id_or_doi)
+        if work:
+            works.append(work)
+    return works
+
+
+def exists(id_or_doi: str) -> bool:
+    """
+    Check if a work exists in the database.
+
+    Args:
+        id_or_doi: OpenAlex ID or DOI
+
+    Returns:
+        True if work exists
+    """
+    if Config.get_mode() == "http":
+        client = _get_http_client()
+        return client.exists(id_or_doi)
+
+    db = get_db()
+
+    # Try as OpenAlex ID first
+    if id_or_doi.startswith("W") or id_or_doi.startswith("w"):
+        row = db.fetchone(
+            "SELECT 1 FROM works WHERE openalex_id = ?", (id_or_doi.upper(),)
+        )
+        if row:
+            return True
+
+    # Try as DOI
+    row = db.fetchone("SELECT 1 FROM works WHERE doi = ?", (id_or_doi,))
+    return row is not None
+
+
+def configure(db_path: str) -> None:
+    """
+    Configure for local database access.
+
+    Args:
+        db_path: Path to OpenAlex SQLite database
+
+    Example:
+        >>> from openalex_local import configure
+        >>> configure("/path/to/openalex.db")
+    """
+    Config.set_db_path(db_path)
+    close_db()
+
+
+def configure_http(api_url: str = "http://localhost:31292") -> None:
+    """
+    Configure for HTTP API access.
+
+    Args:
+        api_url: URL of OpenAlex Local API server
+
+    Example:
+        >>> from openalex_local import configure_http
+        >>> configure_http("http://localhost:31292")
+    """
+    Config.set_api_url(api_url)
+
+
+def get_mode() -> str:
+    """
+    Get current mode.
+
+    Returns:
+        "db" or "http"
+    """
+    return Config.get_mode()
+
+
+def info() -> dict:
+    """
+    Get database/API information.
+
+    Returns:
+        Dictionary with database stats and mode info
+
+    Raises:
+        FileNotFoundError: If no database configured and HTTP mode unavailable
+    """
+    mode = Config.get_mode()
+
+    if mode == "http":
+        client = _get_http_client()
+        http_info = client.info()
+        return {"mode": "http", "status": "ok", **http_info}
+
+    # DB mode - will raise FileNotFoundError if no database
+    db = get_db()
+
+    # Get work count from metadata (fast) or fallback to MAX(rowid) approximation
+    work_count = 0
+    try:
+        row = db.fetchone("SELECT value FROM _metadata WHERE key = 'total_works'")
+        if row:
+            work_count = int(row["value"])
+    except Exception:
+        pass
+
+    if work_count == 0:
+        # Fallback: use MAX(rowid) as approximation (much faster than COUNT(*))
+        try:
+            row = db.fetchone("SELECT MAX(rowid) as count FROM works")
+            work_count = row["count"] if row else 0
+        except Exception:
+            work_count = 0
+
+    # Get FTS count from metadata (fast) or fallback
+    fts_count = 0
+    try:
+        row = db.fetchone("SELECT value FROM _metadata WHERE key = 'fts_total_indexed'")
+        if row:
+            fts_count = int(row["value"])
+    except Exception:
+        pass
+
+    if fts_count == 0:
+        try:
+            row = db.fetchone("SELECT MAX(rowid) as count FROM works_fts")
+            fts_count = row["count"] if row else 0
+        except Exception:
+            fts_count = 0
+
+    # Check for sources table
+    sources_count = 0
+    has_sources = False
+    try:
+        if db.has_sources_table():
+            has_sources = True
+            row = db.fetchone("SELECT COUNT(*) as count FROM sources")
+            sources_count = row["count"] if row else 0
+    except Exception:
+        pass
+
+    return {
+        "status": "ok",
+        "mode": "db",
+        "db_path": str(Config.get_db_path()),
+        "work_count": work_count,
+        "fts_indexed": fts_count,
+        "has_sources": has_sources,
+        "sources_count": sources_count,
+    }
+
+
+def enrich(
+    results: SearchResult,
+    include_abstract: bool = True,
+    include_concepts: bool = True,
+) -> SearchResult:
+    """
+    Enrich search results with full metadata.
+
+    This function re-fetches works from the database to ensure all fields
+    are populated, including abstract and concepts which may be truncated
+    in search results.
+
+    Args:
+        results: SearchResult from a search query
+        include_abstract: Include full abstract text (default True)
+        include_concepts: Include concept/topic data (default True)
+
+    Returns:
+        SearchResult with enriched Work objects
+
+    Example:
+        >>> results = search("machine learning", limit=10)
+        >>> enriched = enrich(results)
+        >>> for work in enriched:
+        ...     print(work.abstract)  # Full abstract available
+    """
+    if not results.works:
+        return results
+
+    # Get full work data for each work
+    ids = [w.openalex_id for w in results.works]
+    enriched_works = get_many(ids)
+
+    # If concepts/abstract not wanted, clear them
+    if not include_abstract:
+        for work in enriched_works:
+            work.abstract = None
+    if not include_concepts:
+        for work in enriched_works:
+            work.concepts = []
+            work.topics = []
+
+    return SearchResult(
+        works=enriched_works,
+        total=results.total,
+        query=results.query,
+        elapsed_ms=results.elapsed_ms,
+    )
+
+
+def enrich_ids(
+    ids: List[str],
+    include_abstract: bool = True,
+    include_concepts: bool = True,
+) -> List[Work]:
+    """
+    Enrich a list of OpenAlex IDs or DOIs with full metadata.
+
+    Args:
+        ids: List of OpenAlex IDs (e.g., W2741809807) or DOIs
+        include_abstract: Include full abstract text (default True)
+        include_concepts: Include concept/topic data (default True)
+
+    Returns:
+        List of Work objects with full metadata
+
+    Example:
+        >>> ids = ["W2741809807", "10.1038/nature12373"]
+        >>> works = enrich_ids(ids)
+        >>> for work in works:
+        ...     print(f"{work.title}: {work.cited_by_count} citations")
+    """
+    works = get_many(ids)
+
+    if not include_abstract:
+        for work in works:
+            work.abstract = None
+    if not include_concepts:
+        for work in works:
+            work.concepts = []
+            work.topics = []
+
+    return works

openalex_local/_core/config.py

@@ -0,0 +1,120 @@
+#!/usr/bin/env python3
+# Timestamp: 2026-01-29
+"""Configuration for openalex_local."""
+
+import os as _os
+from pathlib import Path as _Path
+from typing import Optional as _Optional
+
+# Default database locations (checked in order)
+DEFAULT_DB_PATHS = [
+    _Path("/home/ywatanabe/proj/openalex-local/data/openalex.db"),
+    _Path("/home/ywatanabe/proj/openalex_local/data/openalex.db"),
+    _Path("/mnt/nas_ug/openalex_local/data/openalex.db"),
+    _Path.home() / ".openalex_local" / "openalex.db",
+    _Path.cwd() / "data" / "openalex.db",
+]
+
+
+def get_db_path() -> _Path:
+    """Get database path from environment or auto-detect."""
+    env_path = _os.environ.get("OPENALEX_LOCAL_DB")
+    if env_path:
+        path = _Path(env_path)
+        if path.exists():
+            return path
+        raise FileNotFoundError(f"OPENALEX_LOCAL_DB path not found: {env_path}")
+
+    for path in DEFAULT_DB_PATHS:
+        if path.exists():
+            return path
+
+    raise FileNotFoundError(
+        "OpenAlex database not found. Set OPENALEX_LOCAL_DB environment variable."
+    )
+
+
+DEFAULT_PORT = 31292
+DEFAULT_HOST = "0.0.0.0"
+
+
+class Config:
+    """Configuration container."""
+
+    _db_path: _Optional[_Path] = None
+    _api_url: _Optional[str] = None
+    _mode: str = "auto"  # "auto", "db", or "http"
+
+    @classmethod
+    def get_db_path(cls) -> _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) -> None:
+        p = _Path(path)
+        if not p.exists():
+            raise FileNotFoundError(f"Database not found: {path}")
+        cls._db_path = p
+        cls._mode = "db"
+
+    @classmethod
+    def get_api_url(cls) -> str:
+        if cls._api_url:
+            return cls._api_url
+        return _os.environ.get(
+            "OPENALEX_LOCAL_API_URL", f"http://localhost:{DEFAULT_PORT}"
+        )
+
+    @classmethod
+    def set_api_url(cls, url: str) -> None:
+        cls._api_url = url.rstrip("/")
+        cls._mode = "http"
+
+    @classmethod
+    def set_mode(cls, mode: str) -> None:
+        """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_mode(cls) -> str:
+        """
+        Get current mode.
+
+        Returns:
+            "db" if using direct database access
+            "http" if using HTTP API
+        """
+        if cls._mode == "auto":
+            # Check environment variable for explicit mode
+            env_mode = _os.environ.get("OPENALEX_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 explicitly
+            if cls._api_url or _os.environ.get("OPENALEX_LOCAL_API_URL"):
+                return "http"
+
+            # Check if local database exists
+            try:
+                get_db_path()
+                return "db"
+            except FileNotFoundError:
+                # No local DB, try http
+                return "http"
+
+        return cls._mode
+
+    @classmethod
+    def reset(cls) -> None:
+        cls._db_path = None
+        cls._api_url = None
+        cls._mode = "auto"
+
+
+# EOF

openalex_local/_core/db.py

@@ -0,0 +1,214 @@
+"""Database connection handling for openalex_local."""
+
+import json as _json
+import sqlite3 as _sqlite3
+from contextlib import contextmanager as _contextmanager
+from pathlib import Path as _Path
+from typing import Any, Dict, Generator, List, Optional
+
+from .config import Config as _Config
+
+__all__ = [
+    "Database",
+    "get_db",
+    "close_db",
+    "connection",
+]
+
+
+class Database:
+    """
+    Database connection manager.
+
+    Supports both direct usage and context manager pattern.
+    """
+
+    def __init__(self, db_path: Optional[str | _Path] = None):
+        """
+        Initialize database connection.
+
+        Args:
+            db_path: Path to database. If None, auto-detects.
+        """
+        if db_path:
+            self.db_path = _Path(db_path)
+        else:
+            self.db_path = _Config.get_db_path()
+
+        self.conn: Optional[_sqlite3.Connection] = None
+        self._connect()
+
+    def _connect(self) -> None:
+        """Establish database connection."""
+        self.conn = _sqlite3.connect(self.db_path, check_same_thread=False)
+        self.conn.row_factory = _sqlite3.Row
+
+    def close(self) -> None:
+        """Close database connection."""
+        if self.conn:
+            self.conn.close()
+            self.conn = None
+
+    def __enter__(self) -> "Database":
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        self.close()
+
+    def execute(self, query: str, params: tuple = ()) -> _sqlite3.Cursor:
+        """Execute SQL query."""
+        return self.conn.execute(query, params)
+
+    def fetchone(self, query: str, params: tuple = ()) -> Optional[_sqlite3.Row]:
+        """Execute query and fetch one result."""
+        cursor = self.execute(query, params)
+        return cursor.fetchone()
+
+    def fetchall(self, query: str, params: tuple = ()) -> List[_sqlite3.Row]:
+        """Execute query and fetch all results."""
+        cursor = self.execute(query, params)
+        return cursor.fetchall()
+
+    def get_work(self, openalex_id: str) -> Optional[Dict[str, Any]]:
+        """
+        Get work data by OpenAlex ID.
+
+        Args:
+            openalex_id: OpenAlex ID (e.g., W2741809807)
+
+        Returns:
+            Work data dictionary or None
+        """
+        row = self.fetchone("SELECT * FROM works WHERE openalex_id = ?", (openalex_id,))
+        if row:
+            return self._row_to_dict(row)
+        return None
+
+    def get_work_by_doi(self, doi: str) -> Optional[Dict[str, Any]]:
+        """
+        Get work data by DOI.
+
+        Args:
+            doi: DOI string
+
+        Returns:
+            Work data dictionary or None
+        """
+        row = self.fetchone("SELECT * FROM works WHERE doi = ?", (doi,))
+        if row:
+            return self._row_to_dict(row)
+        return None
+
+    def _row_to_dict(self, row: _sqlite3.Row) -> Dict[str, Any]:
+        """Convert SQLite row to dictionary, parsing JSON fields."""
+        result = dict(row)
+
+        # Parse JSON fields
+        for field in ["authors_json", "concepts_json", "topics_json"]:
+            if field in result and result[field]:
+                try:
+                    result[field.replace("_json", "")] = _json.loads(result[field])
+                except (TypeError, _json.JSONDecodeError):
+                    result[field.replace("_json", "")] = []
+
+        # Parse raw_json if present
+        if "raw_json" in result and result["raw_json"]:
+            try:
+                result["raw"] = _json.loads(result["raw_json"])
+            except (TypeError, _json.JSONDecodeError):
+                result["raw"] = {}
+
+        return result
+
+    def get_source_metrics(self, issn: str) -> Optional[Dict[str, Any]]:
+        """
+        Get source/journal metrics by ISSN.
+
+        Args:
+            issn: Journal ISSN
+
+        Returns:
+            Dictionary with impact_factor, h_index, cited_by_count or None
+        """
+        if not issn:
+            return None
+
+        # Try lookup via issn_lookup table first (fast)
+        row = self.fetchone(
+            """
+            SELECT s.two_year_mean_citedness as impact_factor,
+                   s.h_index as source_h_index,
+                   s.cited_by_count as source_cited_by_count,
+                   s.display_name as source_name
+            FROM issn_lookup l
+            JOIN sources s ON l.source_id = s.id
+            WHERE l.issn = ?
+            """,
+            (issn,),
+        )
+        if row:
+            return dict(row)
+
+        # Fallback: search in sources.issns JSON field
+        row = self.fetchone(
+            """
+            SELECT two_year_mean_citedness as impact_factor,
+                   h_index as source_h_index,
+                   cited_by_count as source_cited_by_count,
+                   display_name as source_name
+            FROM sources
+            WHERE issn_l = ? OR issns LIKE ?
+            """,
+            (issn, f'%"{issn}"%'),
+        )
+        if row:
+            return dict(row)
+
+        return None
+
+    def has_sources_table(self) -> bool:
+        """Check if sources table exists."""
+        row = self.fetchone(
+            "SELECT 1 FROM sqlite_master WHERE type='table' AND name='sources'"
+        )
+        return row is not None
+
+
+# Singleton connection for convenience functions
+_db: Optional[Database] = None
+
+
+def get_db() -> Database:
+    """Get or create singleton database connection."""
+    global _db
+    if _db is None:
+        _db = Database()
+    return _db
+
+
+def close_db() -> None:
+    """Close singleton database connection."""
+    global _db
+    if _db:
+        _db.close()
+        _db = None
+
+
+@_contextmanager
+def connection(
+    db_path: Optional[str | _Path] = None,
+) -> Generator[Database, None, None]:
+    """
+    Context manager for database connection.
+
+    Args:
+        db_path: Path to database. If None, auto-detects.
+
+    Yields:
+        Database instance
+    """
+    db = Database(db_path)
+    try:
+        yield db
+    finally:
+        db.close()