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

crossref_local/_server/routes_collections.py

@@ -0,0 +1,282 @@
+"""Collection management endpoints with file download support."""
+
+import tempfile
+from typing import Optional
+
+from fastapi import APIRouter, Query, HTTPException, Request
+from fastapi.responses import FileResponse
+
+from .. import cache
+from .._cache.utils import sanitize_name
+from .models import CollectionCreateRequest, CollectionInfo
+
+
+# Allowed fields for field filtering (whitelist)
+ALLOWED_FIELDS = {
+    "doi",
+    "title",
+    "authors",
+    "year",
+    "journal",
+    "volume",
+    "issue",
+    "page",
+    "abstract",
+    "citation_count",
+    "references",
+    "issn",
+    "publisher",
+}
+
+# Maximum limits
+MAX_LIMIT = 10000
+MAX_DOIS = 1000
+
+router = APIRouter(prefix="/collections", tags=["collections"])
+
+
+def _get_user_id(request: Request) -> Optional[str]:
+    """Get user ID from request state (set by middleware)."""
+    return getattr(request.state, "user_id", None)
+
+
+@router.get("")
+def list_collections(request: Request):
+    """
+    List all collections.
+
+    For cloud API (with X-User-ID header), returns only user's collections.
+    For local API, returns all collections.
+    """
+    user_id = _get_user_id(request)
+    caches = cache.list_caches(user_id=user_id)
+    return {
+        "count": len(caches),
+        "collections": [c.to_dict() for c in caches],
+    }
+
+
+@router.post("", response_model=CollectionInfo)
+def create_collection(request: Request, body: CollectionCreateRequest):
+    """
+    Create a new collection from search query or DOI list.
+
+    Request body:
+        {"name": "epilepsy", "query": "epilepsy seizure", "limit": 500}
+        or
+        {"name": "my_papers", "dois": ["10.1038/...", "10.1016/..."]}
+    """
+    user_id = _get_user_id(request)
+
+    # Validate collection name
+    try:
+        sanitize_name(body.name)
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+    if not body.query and not body.dois:
+        raise HTTPException(
+            status_code=400,
+            detail="Must provide 'query' or 'dois'",
+        )
+
+    # Validate limits
+    if body.limit > MAX_LIMIT:
+        raise HTTPException(
+            status_code=400,
+            detail=f"Limit exceeds maximum ({MAX_LIMIT})",
+        )
+
+    if body.dois and len(body.dois) > MAX_DOIS:
+        raise HTTPException(
+            status_code=400,
+            detail=f"Too many DOIs ({len(body.dois)}). Maximum: {MAX_DOIS}",
+        )
+
+    try:
+        info = cache.create(
+            body.name,
+            query=body.query,
+            dois=body.dois,
+            limit=body.limit,
+            user_id=user_id,
+        )
+        return CollectionInfo(**info.to_dict())
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get("/{name}")
+def query_collection(
+    name: str,
+    request: Request,
+    fields: Optional[str] = Query(None, description="Comma-separated field list"),
+    include_abstract: bool = Query(False, description="Include abstracts"),
+    include_references: bool = Query(False, description="Include references"),
+    include_citations: bool = Query(False, description="Include citation counts"),
+    year_min: Optional[int] = Query(None, description="Filter by min year"),
+    year_max: Optional[int] = Query(None, description="Filter by max year"),
+    journal: Optional[str] = Query(None, description="Filter by journal"),
+    limit: Optional[int] = Query(None, description="Max results"),
+):
+    """
+    Query a collection with field filtering.
+
+    Returns minimal data to reduce response size.
+    Use 'fields' parameter to specify exactly which fields to return.
+
+    Examples:
+        /collections/epilepsy?fields=doi,title,year
+        /collections/epilepsy?year_min=2020&include_citations=true
+    """
+    user_id = _get_user_id(request)
+
+    # Validate collection name
+    try:
+        sanitize_name(name)
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+    if not cache.exists(name, user_id=user_id):
+        raise HTTPException(status_code=404, detail=f"Collection not found: {name}")
+
+    # Validate and filter fields
+    field_list = None
+    if fields:
+        field_list = [f.strip() for f in fields.split(",")]
+        invalid_fields = set(field_list) - ALLOWED_FIELDS
+        if invalid_fields:
+            raise HTTPException(
+                status_code=400,
+                detail=f"Invalid fields: {invalid_fields}. Allowed: {ALLOWED_FIELDS}",
+            )
+
+    papers = cache.query(
+        name,
+        fields=field_list,
+        include_abstract=include_abstract,
+        include_references=include_references,
+        include_citations=include_citations,
+        year_min=year_min,
+        year_max=year_max,
+        journal=journal,
+        limit=limit,
+        user_id=user_id,
+    )
+
+    return {
+        "name": name,
+        "count": len(papers),
+        "papers": papers,
+    }
+
+
+@router.get("/{name}/stats")
+def collection_stats(name: str, request: Request):
+    """
+    Get collection statistics.
+
+    Returns year distribution, top journals, citation stats.
+    """
+    user_id = _get_user_id(request)
+
+    try:
+        sanitize_name(name)
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+    if not cache.exists(name, user_id=user_id):
+        raise HTTPException(status_code=404, detail=f"Collection not found: {name}")
+
+    stats = cache.stats(name, user_id=user_id)
+    return {"name": name, **stats}
+
+
+@router.get("/{name}/download")
+def download_collection(
+    name: str,
+    request: Request,
+    format: str = Query("json", description="Export format: json, csv, bibtex, dois"),
+    fields: Optional[str] = Query(None, description="Fields to include (json/csv)"),
+):
+    """
+    Download collection as a file.
+
+    Supports multiple formats:
+    - json: Full JSON with all fields or specified fields
+    - csv: CSV format with specified fields
+    - bibtex: BibTeX format for bibliography
+    - dois: Plain text list of DOIs
+
+    Examples:
+        /collections/epilepsy/download?format=json
+        /collections/epilepsy/download?format=bibtex
+        /collections/epilepsy/download?format=csv&fields=doi,title,year
+    """
+    user_id = _get_user_id(request)
+
+    try:
+        sanitize_name(name)
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+    if not cache.exists(name, user_id=user_id):
+        raise HTTPException(status_code=404, detail=f"Collection not found: {name}")
+
+    # Determine file extension and media type
+    format_info = {
+        "json": ("application/json", ".json"),
+        "csv": ("text/csv", ".csv"),
+        "bibtex": ("application/x-bibtex", ".bib"),
+        "dois": ("text/plain", ".txt"),
+    }
+
+    if format not in format_info:
+        raise HTTPException(
+            status_code=400,
+            detail=f"Unsupported format: {format}. Use: json, csv, bibtex, dois",
+        )
+
+    media_type, ext = format_info[format]
+    filename = f"{name}{ext}"
+
+    # Export to temporary file
+    with tempfile.NamedTemporaryFile(mode="w", suffix=ext, delete=False) as tmp:
+        field_list = fields.split(",") if fields else None
+        cache.export(
+            name,
+            tmp.name,
+            format=format,
+            fields=field_list,
+            user_id=user_id,
+        )
+        tmp_path = tmp.name
+
+    return FileResponse(
+        tmp_path,
+        media_type=media_type,
+        filename=filename,
+        headers={"Content-Disposition": f'attachment; filename="{filename}"'},
+    )
+
+
+@router.delete("/{name}")
+def delete_collection(name: str, request: Request):
+    """
+    Delete a collection.
+    """
+    user_id = _get_user_id(request)
+
+    try:
+        sanitize_name(name)
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+    if not cache.exists(name, user_id=user_id):
+        raise HTTPException(status_code=404, detail=f"Collection not found: {name}")
+
+    deleted = cache.delete(name, user_id=user_id)
+
+    return {"deleted": deleted, "name": name}

crossref_local/_server/routes_compat.py

@@ -0,0 +1,102 @@
+"""Backwards-compatible legacy API endpoints."""
+
+from typing import Optional
+
+from fastapi import APIRouter, HTTPException
+
+from .._core import fts
+from .._core.db import get_db
+from .._core.models import Work
+from .models import WorkResponse
+from .routes_works import get_work
+
+router = APIRouter(prefix="/api", tags=["legacy"])
+
+
+@router.get("/search/")
+def api_search_compat(
+    title: Optional[str] = None,
+    q: Optional[str] = None,
+    doi: Optional[str] = None,
+    limit: int = 10,
+):
+    """Backwards-compatible search endpoint."""
+    query = title or q
+
+    if doi:
+        # DOI lookup
+        try:
+            work = get_work(doi)
+            return {
+                "query": {"doi": doi},
+                "results": [work.model_dump()],
+                "total": 1,
+                "returned": 1,
+            }
+        except HTTPException:
+            return {"query": {"doi": doi}, "results": [], "total": 0, "returned": 0}
+
+    if not query:
+        raise HTTPException(
+            status_code=400, detail="Specify q, title, or doi parameter"
+        )
+
+    # Call fts.search directly (not the endpoint function)
+    results = fts.search(query, limit=limit, offset=0)
+    return {
+        "query": {
+            "title": query,
+            "doi": None,
+            "year": None,
+            "authors": None,
+            "limit": limit,
+        },
+        "results": [
+            WorkResponse(
+                doi=w.doi,
+                title=w.title,
+                authors=w.authors,
+                year=w.year,
+                journal=w.journal,
+                issn=w.issn,
+                volume=w.volume,
+                issue=w.issue,
+                page=w.page,
+                abstract=w.abstract,
+                citation_count=w.citation_count,
+            ).model_dump()
+            for w in results.works
+        ],
+        "total": results.total,
+        "returned": len(results.works),
+    }
+
+
+@router.get("/stats/")
+def api_stats_compat():
+    """Backwards-compatible stats endpoint."""
+    db = get_db()
+
+    row = db.fetchone("SELECT COUNT(*) as count FROM works")
+    work_count = row["count"] if row else 0
+
+    # Get table names
+    tables = []
+    for row in db.fetchall("SELECT name FROM sqlite_master WHERE type='table'"):
+        tables.append(row["name"])
+
+    # Get index names
+    indices = []
+    for row in db.fetchall("SELECT name FROM sqlite_master WHERE type='index'"):
+        if row["name"]:
+            indices.append(row["name"])
+
+    return {
+        "total_papers": work_count,
+        "database_size_mb": None,
+        "year_range": None,
+        "total_journals": 0,
+        "total_citations": None,
+        "tables": tables,
+        "indices": indices,
+    }

crossref_local/_server/routes_works.py

@@ -0,0 +1,128 @@
+"""Work search and retrieval endpoints."""
+
+import time
+from typing import Optional
+
+from fastapi import APIRouter, Query, HTTPException
+
+from .._core import fts
+from .._core.db import get_db
+from .._core.models import Work
+from .models import WorkResponse, SearchResponse, BatchRequest, BatchResponse
+
+router = APIRouter(tags=["works"])
+
+
+@router.get("/works", response_model=SearchResponse)
+def search_works(
+    q: str = Query(..., description="Search query (FTS5 syntax supported)"),
+    limit: int = Query(10, ge=1, le=100, 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, abstracts, and authors.
+    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=[
+            WorkResponse(
+                doi=w.doi,
+                title=w.title,
+                authors=w.authors,
+                year=w.year,
+                journal=w.journal,
+                issn=w.issn,
+                volume=w.volume,
+                issue=w.issue,
+                page=w.page,
+                abstract=w.abstract,
+                citation_count=w.citation_count,
+            )
+            for w in results.works
+        ],
+    )
+
+
+@router.get("/works/{doi:path}", response_model=Optional[WorkResponse])
+def get_work(doi: str):
+    """
+    Get work metadata by DOI.
+
+    Examples:
+        /works/10.1038/nature12373
+        /works/10.1016/j.cell.2020.01.001
+    """
+    db = get_db()
+    metadata = db.get_metadata(doi)
+
+    if metadata is None:
+        raise HTTPException(status_code=404, detail=f"DOI not found: {doi}")
+
+    work = Work.from_metadata(doi, metadata)
+
+    return WorkResponse(
+        doi=work.doi,
+        title=work.title,
+        authors=work.authors,
+        year=work.year,
+        journal=work.journal,
+        issn=work.issn,
+        volume=work.volume,
+        issue=work.issue,
+        page=work.page,
+        abstract=work.abstract,
+        citation_count=work.citation_count,
+    )
+
+
+@router.post("/works/batch", response_model=BatchResponse)
+def get_works_batch(request: BatchRequest):
+    """
+    Get multiple works by DOI.
+
+    Request body: {"dois": ["10.1038/...", "10.1016/..."]}
+    """
+    db = get_db()
+    results = []
+
+    for doi in request.dois:
+        metadata = db.get_metadata(doi)
+        if metadata:
+            work = Work.from_metadata(doi, metadata)
+            results.append(
+                WorkResponse(
+                    doi=work.doi,
+                    title=work.title,
+                    authors=work.authors,
+                    year=work.year,
+                    journal=work.journal,
+                    abstract=work.abstract,
+                    citation_count=work.citation_count,
+                )
+            )
+
+    return BatchResponse(
+        requested=len(request.dois),
+        found=len(results),
+        results=results,
+    )

crossref_local/_server/server.py

@@ -0,0 +1,19 @@
+"""FastAPI server for CrossRef Local with FTS5 search.
+
+This module re-exports from the modular server package for backwards compatibility.
+
+Usage:
+    crossref-local api                    # Run on default port 31291
+    crossref-local api --port 8080        # Custom port
+
+    # Or directly:
+    uvicorn crossref_local.server:app --host 0.0.0.0 --port 31291
+"""
+
+# Re-export from modular server package
+from .server import app, run_server, DEFAULT_PORT, DEFAULT_HOST
+
+__all__ = ["app", "run_server", "DEFAULT_PORT", "DEFAULT_HOST"]
+
+if __name__ == "__main__":
+    run_server()