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

openalex_local/_remote/base.py

@@ -0,0 +1,256 @@
+"""Remote API client for openalex_local.
+
+Connects to an OpenAlex Local API server instead of direct database access.
+Use this when the database is on a remote server accessible via HTTP.
+"""
+
+import json
+import urllib.request
+import urllib.parse
+import urllib.error
+from typing import List, Optional, Dict, Any
+
+from .._core.models import Work, SearchResult
+from .._core.config import DEFAULT_PORT
+
+# Default URL uses SCITEX port convention
+DEFAULT_API_URL = f"http://localhost:{DEFAULT_PORT}"
+
+
+class RemoteClient:
+    """
+    HTTP client for OpenAlex Local API server.
+
+    Provides the same interface as the local API but connects
+    to a remote server via HTTP.
+
+    Example:
+        >>> client = RemoteClient("http://localhost:31292")
+        >>> results = client.search(query="machine learning", limit=10)
+        >>> work = client.get("W2741809807")
+    """
+
+    def __init__(self, base_url: str = DEFAULT_API_URL, timeout: int = 30):
+        """
+        Initialize remote client.
+
+        Args:
+            base_url: API server URL (default: http://localhost:31292)
+            timeout: Request timeout in seconds
+        """
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    def _request(
+        self,
+        endpoint: str,
+        params: Optional[Dict[str, Any]] = None,
+        method: str = "GET",
+        data: Optional[Dict[str, Any]] = None,
+    ) -> Optional[Dict]:
+        """Make HTTP request to API."""
+        url = f"{self.base_url}{endpoint}"
+        if params:
+            # Filter out None values
+            params = {k: v for k, v in params.items() if v is not None}
+            if params:
+                url = f"{url}?{urllib.parse.urlencode(params)}"
+
+        try:
+            req_data = None
+            if data is not None:
+                req_data = json.dumps(data).encode("utf-8")
+
+            req = urllib.request.Request(url, data=req_data, method=method)
+            req.add_header("Accept", "application/json")
+            if req_data:
+                req.add_header("Content-Type", "application/json")
+
+            with urllib.request.urlopen(req, timeout=self.timeout) as response:
+                return json.loads(response.read().decode("utf-8"))
+        except urllib.error.HTTPError as e:
+            if e.code == 404:
+                return None
+            raise ConnectionError(f"API request failed: {e.code} {e.reason}") from e
+        except urllib.error.URLError as e:
+            raise ConnectionError(
+                f"Cannot connect to API at {self.base_url}: {e.reason}"
+            ) from e
+        except (ConnectionRefusedError, ConnectionResetError, OSError) as e:
+            raise ConnectionError(
+                f"Cannot connect to API at {self.base_url}: {e}"
+            ) from e
+
+    def health(self) -> Dict:
+        """Check API server health."""
+        return self._request("/health")
+
+    def info(self) -> Dict:
+        """Get database/API information."""
+        root = self._request("/")
+        info_data = self._request("/info")
+        return {
+            "api_url": self.base_url,
+            "api_version": root.get("version", "unknown") if root else "unknown",
+            "status": root.get("status", "unknown") if root else "unknown",
+            "mode": "remote",
+            "works": info_data.get("total_works", 0) if info_data else 0,
+            "fts_indexed": info_data.get("fts_indexed", 0) if info_data else 0,
+        }
+
+    def search(
+        self,
+        query: str,
+        limit: int = 20,
+        offset: int = 0,
+    ) -> SearchResult:
+        """
+        Search for works.
+
+        Args:
+            query: Full-text search query
+            limit: Maximum results (default: 20)
+            offset: Skip first N results for pagination
+
+        Returns:
+            SearchResult with matching works
+        """
+        params = {
+            "q": query,
+            "limit": limit,
+            "offset": offset,
+        }
+
+        data = self._request("/works", params)
+
+        if not data:
+            return SearchResult(works=[], total=0, query=query, elapsed_ms=0.0)
+
+        works = []
+        for item in data.get("results", []):
+            work = Work(
+                openalex_id=item.get("openalex_id", ""),
+                doi=item.get("doi"),
+                title=item.get("title"),
+                authors=item.get("authors", []),
+                year=item.get("year"),
+                source=item.get("source"),
+                issn=item.get("issn"),
+                volume=item.get("volume"),
+                issue=item.get("issue"),
+                pages=item.get("pages"),
+                abstract=item.get("abstract"),
+                cited_by_count=item.get("cited_by_count"),
+                concepts=item.get("concepts", []),
+                topics=item.get("topics", []),
+                is_oa=item.get("is_oa", False),
+                oa_url=item.get("oa_url"),
+            )
+            works.append(work)
+
+        return SearchResult(
+            works=works,
+            total=data.get("total", len(works)),
+            query=query,
+            elapsed_ms=data.get("elapsed_ms", 0.0),
+        )
+
+    def get(self, 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
+        """
+        data = self._request(f"/works/{id_or_doi}")
+        if not data or "error" in data:
+            return None
+
+        return Work(
+            openalex_id=data.get("openalex_id", ""),
+            doi=data.get("doi"),
+            title=data.get("title"),
+            authors=data.get("authors", []),
+            year=data.get("year"),
+            source=data.get("source"),
+            issn=data.get("issn"),
+            volume=data.get("volume"),
+            issue=data.get("issue"),
+            pages=data.get("pages"),
+            abstract=data.get("abstract"),
+            cited_by_count=data.get("cited_by_count"),
+            concepts=data.get("concepts", []),
+            topics=data.get("topics", []),
+            is_oa=data.get("is_oa", False),
+            oa_url=data.get("oa_url"),
+        )
+
+    def get_many(self, ids: List[str]) -> List[Work]:
+        """
+        Get multiple works by OpenAlex ID or DOI using batch endpoint.
+
+        Args:
+            ids: List of OpenAlex IDs or DOIs
+
+        Returns:
+            List of Work objects
+        """
+        try:
+            data = {"ids": ids}
+            req_data = json.dumps(data).encode("utf-8")
+            req = urllib.request.Request(
+                f"{self.base_url}/works/batch", data=req_data, method="POST"
+            )
+            req.add_header("Content-Type", "application/json")
+            req.add_header("Accept", "application/json")
+
+            with urllib.request.urlopen(req, timeout=self.timeout) as response:
+                result = json.loads(response.read().decode("utf-8"))
+
+            works = []
+            for item in result.get("results", []):
+                work = Work(
+                    openalex_id=item.get("openalex_id", ""),
+                    doi=item.get("doi"),
+                    title=item.get("title"),
+                    authors=item.get("authors", []),
+                    year=item.get("year"),
+                    source=item.get("source"),
+                    abstract=item.get("abstract"),
+                    cited_by_count=item.get("cited_by_count"),
+                )
+                works.append(work)
+            return works
+        except Exception:
+            # Fallback to individual lookups
+            works = []
+            for id_or_doi in ids:
+                work = self.get(id_or_doi)
+                if work:
+                    works.append(work)
+            return works
+
+    def exists(self, id_or_doi: str) -> bool:
+        """Check if a work exists."""
+        return self.get(id_or_doi) is not None
+
+
+# Module-level client for convenience
+_client: Optional[RemoteClient] = None
+
+
+def get_client(base_url: str = DEFAULT_API_URL) -> RemoteClient:
+    """Get or create singleton remote client."""
+    global _client
+    if _client is None or _client.base_url != base_url:
+        _client = RemoteClient(base_url)
+    return _client
+
+
+def reset_client() -> None:
+    """Reset singleton client."""
+    global _client
+    _client = None

openalex_local/_server/__init__.py

@@ -0,0 +1,117 @@
+"""FastAPI server for OpenAlex Local with FTS5 search.
+
+Provides HTTP relay server for remote database access.
+
+Usage:
+    openalex-local relay                    # Run on default port 31292
+    openalex-local relay --port 8080        # Custom port
+
+    # Or directly:
+    uvicorn openalex_local.server:app --host 0.0.0.0 --port 31292
+"""
+
+import os
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from .. import __version__
+from .routes import router
+
+# Create FastAPI app
+app = FastAPI(
+    title="OpenAlex Local API",
+    description="Fast full-text search across 284M+ scholarly works",
+    version=__version__,
+)
+
+# CORS middleware
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Include routes
+app.include_router(router)
+
+
+@app.get("/")
+def root():
+    """API root with endpoint information."""
+    return {
+        "name": "OpenAlex Local API",
+        "version": __version__,
+        "status": "running",
+        "endpoints": {
+            "health": "/health",
+            "info": "/info",
+            "search": "/works?q=<query>",
+            "get_by_id": "/works/{id_or_doi}",
+            "batch": "/works/batch",
+        },
+    }
+
+
+@app.get("/health")
+def health():
+    """Health check endpoint."""
+    from .._core.db import get_db
+
+    try:
+        db = get_db()
+        return {
+            "status": "healthy",
+            "database_connected": db is not None,
+            "database_path": str(db.db_path) if db else None,
+        }
+    except Exception as e:
+        return {
+            "status": "unhealthy",
+            "error": str(e),
+        }
+
+
+@app.get("/info")
+def info():
+    """Get database statistics."""
+    from .._core.db import get_db
+
+    db = get_db()
+
+    row = db.fetchone("SELECT COUNT(*) as count FROM works")
+    work_count = row["count"] if row else 0
+
+    try:
+        row = db.fetchone("SELECT COUNT(*) as count FROM works_fts")
+        fts_count = row["count"] if row else 0
+    except Exception:
+        fts_count = 0
+
+    return {
+        "name": "OpenAlex Local API",
+        "version": __version__,
+        "status": "running",
+        "mode": "local",
+        "total_works": work_count,
+        "fts_indexed": fts_count,
+        "database_path": str(db.db_path),
+    }
+
+
+# Default port: SCITEX convention (3129X scheme)
+DEFAULT_PORT = int(os.environ.get("OPENALEX_LOCAL_PORT", "31292"))
+DEFAULT_HOST = os.environ.get("OPENALEX_LOCAL_HOST", "0.0.0.0")
+
+
+def run_server(host: str = None, port: int = None):
+    """Run the FastAPI server."""
+    import uvicorn
+
+    host = host or DEFAULT_HOST
+    port = port or DEFAULT_PORT
+    uvicorn.run(app, host=host, port=port)
+
+
+__all__ = ["app", "run_server", "DEFAULT_PORT", "DEFAULT_HOST"]

openalex_local/_server/routes.py

@@ -0,0 +1,175 @@
+"""Work search and retrieval endpoints."""
+
+import time
+from typing import Optional, List
+
+from fastapi import APIRouter, Query, HTTPException
+from pydantic import BaseModel
+
+from .._core import fts
+from .._core.db import get_db
+from .._core.models import Work
+
+router = APIRouter(tags=["works"])
+
+
+# Pydantic models for responses
+class WorkResponse(BaseModel):
+    """Work metadata response."""
+
+    openalex_id: str
+    doi: Optional[str] = None
+    title: Optional[str] = None
+    authors: List[str] = []
+    year: Optional[int] = None
+    source: Optional[str] = None
+    issn: Optional[str] = None
+    volume: Optional[str] = None
+    issue: Optional[str] = None
+    pages: Optional[str] = None
+    abstract: Optional[str] = None
+    cited_by_count: Optional[int] = None
+    concepts: List[dict] = []
+    topics: List[dict] = []
+    is_oa: bool = False
+    oa_url: Optional[str] = None
+
+
+class SearchResponse(BaseModel):
+    """Search results response."""
+
+    query: str
+    total: int
+    returned: int
+    elapsed_ms: float
+    results: List[WorkResponse]
+
+
+class BatchRequest(BaseModel):
+    """Batch ID lookup request."""
+
+    ids: List[str]
+
+
+class BatchResponse(BaseModel):
+    """Batch ID lookup response."""
+
+    requested: int
+    found: int
+    results: List[WorkResponse]
+
+
+def _work_to_response(work: Work) -> WorkResponse:
+    """Convert Work to WorkResponse."""
+    return WorkResponse(
+        openalex_id=work.openalex_id,
+        doi=work.doi,
+        title=work.title,
+        authors=work.authors,
+        year=work.year,
+        source=work.source,
+        issn=work.issn,
+        volume=work.volume,
+        issue=work.issue,
+        pages=work.pages,
+        abstract=work.abstract,
+        cited_by_count=work.cited_by_count,
+        concepts=work.concepts,
+        topics=work.topics,
+        is_oa=work.is_oa,
+        oa_url=work.oa_url,
+    )
+
+
+@router.get("/works", response_model=SearchResponse)
+def search_works(
+    q: str = Query(..., description="Search query (FTS5 syntax supported)"),
+    limit: int = Query(20, ge=1, description="Max results"),
+    offset: int = Query(0, ge=0, description="Skip first N results"),
+):
+    """
+    Full-text search across works.
+
+    Uses FTS5 index for fast searching across titles and abstracts.
+    Supports FTS5 query syntax like AND, OR, NOT, "exact phrases".
+
+    Examples:
+        /works?q=machine learning
+        /works?q="neural network" AND hippocampus
+        /works?q=CRISPR&limit=20
+    """
+    start = time.perf_counter()
+
+    try:
+        results = fts.search(q, limit=limit, offset=offset)
+    except Exception as e:
+        raise HTTPException(status_code=400, detail=f"Search error: {e}")
+
+    elapsed_ms = (time.perf_counter() - start) * 1000
+
+    return SearchResponse(
+        query=q,
+        total=results.total,
+        returned=len(results.works),
+        elapsed_ms=round(elapsed_ms, 2),
+        results=[_work_to_response(w) for w in results.works],
+    )
+
+
+@router.get("/works/{id_or_doi:path}", response_model=Optional[WorkResponse])
+def get_work(id_or_doi: str):
+    """
+    Get work metadata by OpenAlex ID or DOI.
+
+    Examples:
+        /works/W2741809807
+        /works/10.1038/nature12373
+    """
+    db = get_db()
+
+    # Try as OpenAlex ID first
+    if id_or_doi.upper().startswith("W"):
+        data = db.get_work(id_or_doi.upper())
+        if data:
+            work = Work.from_db_row(data)
+            return _work_to_response(work)
+
+    # Try as DOI
+    data = db.get_work_by_doi(id_or_doi)
+    if data:
+        work = Work.from_db_row(data)
+        return _work_to_response(work)
+
+    raise HTTPException(status_code=404, detail=f"Not found: {id_or_doi}")
+
+
+@router.post("/works/batch", response_model=BatchResponse)
+def get_works_batch(request: BatchRequest):
+    """
+    Get multiple works by OpenAlex ID or DOI.
+
+    Request body: {"ids": ["W2741809807", "10.1038/..."]}
+    """
+    db = get_db()
+    results = []
+
+    for id_or_doi in request.ids:
+        data = None
+
+        # Try as OpenAlex ID first
+        if id_or_doi.upper().startswith("W"):
+            data = db.get_work(id_or_doi.upper())
+
+        # Try as DOI
+        if not data:
+            data = db.get_work_by_doi(id_or_doi)
+
+        if data:
+            work = Work.from_db_row(data)
+            results.append(_work_to_response(work))
+
+    return BatchResponse(
+        requested=len(request.ids),
+        found=len(results),
+        results=results,
+    )