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

crossref_local/cli.py

@@ -2,17 +2,15 @@
 
 import click
 import json
-import logging
 import re
 import sys
 from typing import Optional
 
-from . import search, get, count, info, __version__
+from rich.console import Console
 
-from .impact_factor import ImpactFactorCalculator
+from . import search, get, info, __version__
 
-# Suppress noisy warnings from impact_factor module in CLI
-logging.getLogger("crossref_local.impact_factor").setLevel(logging.ERROR)
+console = Console()
 
 
 def _strip_xml_tags(text: str) -> str:
@@ -76,30 +74,61 @@ class AliasedGroup(click.Group):
 CONTEXT_SETTINGS = {"help_option_names": ["-h", "--help"]}
 
 
+def _print_recursive_help(ctx, param, value):
+    """Callback for --help-recursive flag."""
+    if not value or ctx.resilient_parsing:
+        return
+
+    def _print_command_help(cmd, prefix: str, parent_ctx):
+        """Recursively print help for a command and its subcommands."""
+        console.print(f"\n[bold cyan]━━━ {prefix} ━━━[/bold cyan]")
+        sub_ctx = click.Context(cmd, info_name=prefix.split()[-1], parent=parent_ctx)
+        console.print(cmd.get_help(sub_ctx))
+
+        if isinstance(cmd, click.Group):
+            for sub_name, sub_cmd in sorted(cmd.commands.items()):
+                _print_command_help(sub_cmd, f"{prefix} {sub_name}", sub_ctx)
+
+    # Print main help
+    console.print("[bold cyan]━━━ crossref-local ━━━[/bold cyan]")
+    console.print(ctx.get_help())
+
+    # Print all subcommands recursively
+    for name, cmd in sorted(cli.commands.items()):
+        _print_command_help(cmd, f"crossref-local {name}", ctx)
+
+    ctx.exit(0)
+
+
 @click.group(cls=AliasedGroup, context_settings=CONTEXT_SETTINGS)
 @click.version_option(version=__version__, prog_name="crossref-local")
+@click.option("--http", is_flag=True, help="Use HTTP API instead of direct database")
 @click.option(
-    "--remote", "-r", is_flag=True, help="Use remote API instead of local database"
+    "--api-url",
+    envvar="CROSSREF_LOCAL_API_URL",
+    help="API URL for http mode (default: auto-detect)",
 )
 @click.option(
-    "--api-url",
-    envvar="CROSSREF_LOCAL_API",
-    help="API URL for remote mode (default: auto-detect)",
+    "--help-recursive",
+    is_flag=True,
+    is_eager=True,
+    expose_value=False,
+    callback=_print_recursive_help,
+    help="Show help for all commands recursively.",
 )
 @click.pass_context
-def cli(ctx, remote: bool, api_url: str):
+def cli(ctx, http: bool, api_url: str):
     """Local CrossRef database with 167M+ works and full-text search.
 
-    Supports both local database access and remote API mode.
+    Supports both direct database access (db mode) and HTTP API (http mode).
 
     \b
-    Local mode (default if database found):
+    DB mode (default if database found):
       crossref-local search "machine learning"
 
     \b
-    Remote mode (via SSH tunnel):
-      ssh -L 3333:127.0.0.1:3333 nas  # First, create tunnel
-      crossref-local --remote search "machine learning"
+    HTTP mode (connect to API server):
+      crossref-local --http search "machine learning"
     """
     from .config import Config
 
@@ -107,8 +136,8 @@ def cli(ctx, remote: bool, api_url: str):
 
     if api_url:
         Config.set_api_url(api_url)
-    elif remote:
-        Config.set_mode("remote")
+    elif http:
+        Config.set_mode("http")
 
 
 def _get_if_fast(db, issn: str, cache: dict) -> Optional[float]:
@@ -117,24 +146,42 @@ def _get_if_fast(db, issn: str, cache: dict) -> Optional[float]:
         return cache[issn]
     row = db.fetchone(
         "SELECT two_year_mean_citedness FROM journals_openalex WHERE issns LIKE ?",
-        (f"%{issn}%",)
+        (f"%{issn}%",),
     )
     cache[issn] = row["two_year_mean_citedness"] if row else None
     return cache[issn]
 
 
-@cli.command("search", aliases=["s"], context_settings=CONTEXT_SETTINGS)
+@cli.command("search", context_settings=CONTEXT_SETTINGS)
 @click.argument("query")
-@click.option("-n", "--number", "limit", default=10, show_default=True, help="Number of results")
+@click.option(
+    "-n", "--number", "limit", default=10, show_default=True, help="Number of results"
+)
 @click.option("-o", "--offset", default=0, help="Skip first N results")
 @click.option("-a", "--abstracts", is_flag=True, help="Show abstracts")
 @click.option("-A", "--authors", is_flag=True, help="Show authors")
-@click.option("-if", "--impact-factor", "with_if", is_flag=True, help="Show journal impact factor")
+@click.option(
+    "-if", "--impact-factor", "with_if", is_flag=True, help="Show journal impact factor"
+)
 @click.option("--json", "as_json", is_flag=True, help="Output as JSON")
-def search_cmd(query: str, limit: int, offset: int, abstracts: bool, authors: bool, with_if: bool, as_json: bool):
+def search_cmd(
+    query: str,
+    limit: int,
+    offset: int,
+    abstracts: bool,
+    authors: bool,
+    with_if: bool,
+    as_json: bool,
+):
     """Search for works by title, abstract, or authors."""
     from .db import get_db
-    results = search(query, limit=limit, offset=offset)
+
+    try:
+        results = search(query, limit=limit, offset=offset)
+    except ConnectionError as e:
+        click.echo(f"Error: {e}", err=True)
+        click.echo("\nRun 'crossref-local status' to check configuration.", err=True)
+        sys.exit(1)
 
     # Cache for fast IF lookups
     if_cache = {}
@@ -177,13 +224,18 @@ def search_cmd(query: str, limit: int, offset: int, abstracts: bool, authors: bo
             click.echo()
 
 
-@cli.command("get", aliases=["g"], context_settings=CONTEXT_SETTINGS)
+@cli.command("search-by-doi", context_settings=CONTEXT_SETTINGS)
 @click.argument("doi")
 @click.option("--json", "as_json", is_flag=True, help="Output as JSON")
 @click.option("--citation", is_flag=True, help="Output as citation")
-def get_cmd(doi: str, as_json: bool, citation: bool):
-    """Get a work by DOI."""
-    work = get(doi)
+def search_by_doi_cmd(doi: str, as_json: bool, citation: bool):
+    """Search for a work by DOI."""
+    try:
+        work = get(doi)
+    except ConnectionError as e:
+        click.echo(f"Error: {e}", err=True)
+        click.echo("\nRun 'crossref-local status' to check configuration.", err=True)
+        sys.exit(1)
 
     if work is None:
         click.echo(f"DOI not found: {doi}", err=True)
@@ -203,92 +255,60 @@ def get_cmd(doi: str, as_json: bool, citation: bool):
             click.echo(f"Citations: {work.citation_count}")
 
 
-@cli.command("count", aliases=["c"], context_settings=CONTEXT_SETTINGS)
-@click.argument("query")
-def count_cmd(query: str):
-    """Count matching works."""
-    n = count(query)
-    click.echo(f"{n:,}")
-
-
-@cli.command("info", aliases=["i"], context_settings=CONTEXT_SETTINGS)
-@click.option("--json", "as_json", is_flag=True, help="Output as JSON")
-def info_cmd(as_json: bool):
-    """Show database/API information."""
-    db_info = info()
-
-    if as_json:
-        click.echo(json.dumps(db_info, indent=2))
-    else:
-        mode = db_info.get("mode", "local")
-        if mode == "remote":
-            click.echo("CrossRef Local API (Remote)")
-            click.echo("-" * 40)
-            click.echo(f"API URL: {db_info.get('api_url', 'unknown')}")
-            click.echo(f"Status: {db_info.get('status', 'unknown')}")
-        else:
-            click.echo("CrossRef Local Database")
-            click.echo("-" * 40)
-            click.echo(f"Database: {db_info.get('db_path', 'unknown')}")
-            click.echo(f"Works: {db_info.get('works', 0):,}")
-            click.echo(f"FTS indexed: {db_info.get('fts_indexed', 0):,}")
-            click.echo(f"Citations: {db_info.get('citations', 0):,}")
-
-
-@cli.command("impact-factor", aliases=["if"], context_settings=CONTEXT_SETTINGS)
-@click.argument("journal")
-@click.option("-y", "--year", default=2023, help="Target year")
-@click.option("-w", "--window", default=2, help="Citation window years")
-@click.option("--json", "as_json", is_flag=True, help="Output as JSON")
-def impact_factor_cmd(journal: str, year: int, window: int, as_json: bool):
-    """Calculate impact factor for a journal."""
-    with ImpactFactorCalculator() as calc:
-        result = calc.calculate_impact_factor(
-            journal_identifier=journal,
-            target_year=year,
-            window_years=window,
-        )
-
-    if as_json:
-        click.echo(json.dumps(result, indent=2))
-    else:
-        click.echo(f"Journal: {result['journal']}")
-        click.echo(f"Year: {result['target_year']}")
-        click.echo(f"Window: {result['window_range']}")
-        click.echo(f"Articles: {result['total_articles']:,}")
-        click.echo(f"Citations: {result['total_citations']:,}")
-        click.echo(f"Impact Factor: {result['impact_factor']:.3f}")
-
-
 @cli.command(context_settings=CONTEXT_SETTINGS)
-def setup():
-    """Check setup status and configuration."""
+def status():
+    """Show status and configuration."""
     from .config import DEFAULT_DB_PATHS, DEFAULT_API_URLS
     import os
 
-    click.echo("CrossRef Local - Setup Status")
+    click.echo("CrossRef Local - Status")
     click.echo("=" * 50)
     click.echo()
 
     # Check environment variables
     click.echo("Environment Variables:")
-    env_db = os.environ.get("CROSSREF_LOCAL_DB")
-    env_api = os.environ.get("CROSSREF_LOCAL_API")
-    env_mode = os.environ.get("CROSSREF_LOCAL_MODE")
-
-    if env_db:
-        status = "OK" if os.path.exists(env_db) else "NOT FOUND"
-        click.echo(f"  CROSSREF_LOCAL_DB: {env_db} ({status})")
-    else:
-        click.echo("  CROSSREF_LOCAL_DB: (not set)")
-
-    if env_api:
-        click.echo(f"  CROSSREF_LOCAL_API: {env_api}")
-    else:
-        click.echo("  CROSSREF_LOCAL_API: (not set)")
+    click.echo()
 
-    if env_mode:
-        click.echo(f"  CROSSREF_LOCAL_MODE: {env_mode}")
+    env_vars = [
+        (
+            "CROSSREF_LOCAL_DB",
+            "Path to SQLite database file",
+            os.environ.get("CROSSREF_LOCAL_DB"),
+        ),
+        (
+            "CROSSREF_LOCAL_API_URL",
+            "HTTP API URL (e.g., http://localhost:8333)",
+            os.environ.get("CROSSREF_LOCAL_API_URL"),
+        ),
+        (
+            "CROSSREF_LOCAL_MODE",
+            "Force mode: 'db', 'http', or 'auto'",
+            os.environ.get("CROSSREF_LOCAL_MODE"),
+        ),
+        (
+            "CROSSREF_LOCAL_HOST",
+            "Host for run-server-http (default: 0.0.0.0)",
+            os.environ.get("CROSSREF_LOCAL_HOST"),
+        ),
+        (
+            "CROSSREF_LOCAL_PORT",
+            "Port for run-server-http (default: 8333)",
+            os.environ.get("CROSSREF_LOCAL_PORT"),
+        ),
+    ]
+
+    for var_name, description, value in env_vars:
+        if value:
+            if var_name == "CROSSREF_LOCAL_DB":
+                status = " (OK)" if os.path.exists(value) else " (NOT FOUND)"
+            else:
+                status = ""
+            click.echo(f"  {var_name}={value}{status}")
+            click.echo(f"      | {description}")
+        else:
+            click.echo(f"  {var_name} (not set)")
+            click.echo(f"      | {description}")
+        click.echo()
 
     click.echo()
 
@@ -305,17 +325,35 @@ def setup():
 
     click.echo()
 
-    # Check remote API endpoints
-    click.echo("Remote API Endpoints:")
+    # Check API servers
+    click.echo("API Servers:")
     api_found = None
+    api_compatible = False
     for url in DEFAULT_API_URLS:
         try:
             import urllib.request
+            import json as json_module
 
-            req = urllib.request.Request(f"{url}/health", method="GET")
+            # Check root endpoint for version
+            req = urllib.request.Request(f"{url}/", method="GET")
+            req.add_header("Accept", "application/json")
             with urllib.request.urlopen(req, timeout=3) as resp:
                 if resp.status == 200:
-                    click.echo(f"  [OK] {url}")
+                    data = json_module.loads(resp.read().decode())
+                    server_version = data.get("version", "unknown")
+
+                    # Check version compatibility
+                    if server_version == __version__:
+                        click.echo(f"  [OK] {url} (v{server_version})")
+                        api_compatible = True
+                    else:
+                        click.echo(
+                            f"  [WARN] {url} (v{server_version} != v{__version__})"
+                        )
+                        click.echo(
+                            f"         Server version mismatch - may be incompatible"
+                        )
+
                     if api_found is None:
                         api_found = url
                 else:
@@ -338,59 +376,81 @@ def setup():
         click.echo("Ready! Try:")
         click.echo('  crossref-local search "machine learning"')
     elif api_found:
-        click.echo(f"Remote API available: {api_found}")
+        click.echo(f"HTTP API available: {api_found}")
         click.echo()
         click.echo("Ready! Try:")
-        click.echo('  crossref-local --remote search "machine learning"')
+        click.echo('  crossref-local --http search "machine learning"')
         click.echo()
         click.echo("Or set environment:")
-        click.echo("  export CROSSREF_LOCAL_MODE=remote")
+        click.echo("  export CROSSREF_LOCAL_MODE=http")
     else:
-        click.echo("No database or API found!")
+        click.echo("No database or API server found!")
         click.echo()
         click.echo("Options:")
-        click.echo("  1. Local database:")
+        click.echo("  1. Direct database access (db mode):")
         click.echo("     export CROSSREF_LOCAL_DB=/path/to/crossref.db")
         click.echo()
-        click.echo("  2. Remote API (via SSH tunnel):")
-        click.echo("     ssh -L 3333:127.0.0.1:3333 your-nas")
-        click.echo("     crossref-local --remote search 'query'")
+        click.echo("  2. HTTP API (connect to server):")
+        click.echo("     crossref-local --http search 'query'")
 
 
-@cli.command(context_settings=CONTEXT_SETTINGS)
+@cli.command("run-server-mcp", context_settings=CONTEXT_SETTINGS)
 @click.option(
     "-t",
     "--transport",
     type=click.Choice(["stdio", "sse", "http"]),
     default="stdio",
-    help="Transport protocol (stdio for Claude Desktop)",
+    help="Transport protocol (http recommended for remote)",
 )
-@click.option("--host", default="localhost", help="Host for HTTP/SSE transport")
-@click.option("--port", default=8082, type=int, help="Port for HTTP/SSE transport")
-def serve(transport: str, host: str, port: int):
-    """Run MCP server for Claude integration.
+@click.option(
+    "--host",
+    default="localhost",
+    envvar="CROSSREF_LOCAL_MCP_HOST",
+    help="Host for HTTP/SSE transport",
+)
+@click.option(
+    "--port",
+    default=8082,
+    type=int,
+    envvar="CROSSREF_LOCAL_MCP_PORT",
+    help="Port for HTTP/SSE transport",
+)
+def serve_mcp(transport: str, host: str, port: int):
+    """Run MCP (Model Context Protocol) server.
 
     \b
-    Claude Desktop configuration (claude_desktop_config.json):
+    Transports:
+      stdio  - Standard I/O (default, for Claude Desktop local)
+      http   - Streamable HTTP (recommended for remote/persistent)
+      sse    - Server-Sent Events (deprecated as of MCP spec 2025-03-26)
+
+    \b
+    Local configuration (stdio):
       {
         "mcpServers": {
           "crossref": {
             "command": "crossref-local",
-            "args": ["serve"]
+            "args": ["run-server-mcp"]
           }
         }
       }
 
     \b
-    Or with explicit path:
+    Remote configuration (http):
+      # Start server:
+      crossref-local run-server-mcp -t http --host 0.0.0.0 --port 8082
+
+      # Client config:
       {
         "mcpServers": {
-          "crossref": {
-            "command": "python",
-            "args": ["-m", "crossref_local.mcp_server"]
+          "crossref-remote": {
+            "url": "http://your-server:8082/mcp"
           }
         }
       }
+
+    \b
+    See docs/remote-deployment.md for systemd and Docker setup.
     """
     try:
         from .mcp_server import run_server
@@ -405,11 +465,19 @@ def serve(transport: str, host: str, port: int):
     run_server(transport=transport, host=host, port=port)
 
 
-@cli.command(context_settings=CONTEXT_SETTINGS)
-@click.option("--host", default="0.0.0.0", help="Host to bind")
-@click.option("--port", default=3333, type=int, help="Port to listen on")
-def api(host: str, port: int):
-    """Run HTTP API server with FTS5 search.
+@cli.command("run-server-http", context_settings=CONTEXT_SETTINGS)
+@click.option(
+    "--host", default="0.0.0.0", envvar="CROSSREF_LOCAL_HOST", help="Host to bind"
+)
+@click.option(
+    "--port",
+    default=8333,
+    type=int,
+    envvar="CROSSREF_LOCAL_PORT",
+    help="Port to listen on",
+)
+def serve_http(host: str, port: int):
+    """Run HTTP API server.
 
     \b
     This runs a FastAPI server that provides proper full-text search
@@ -417,13 +485,13 @@ def api(host: str, port: int):
 
     \b
     Example:
-      crossref-local api                  # Run on 0.0.0.0:3333
-      crossref-local api --port 8080      # Custom port
+      crossref-local run-server-http                  # Run on 0.0.0.0:8333
+      crossref-local run-server-http --port 8080      # Custom port
 
     \b
-    Then from a client:
-      curl "http://localhost:3333/search?q=CRISPR&limit=10"
-      curl "http://localhost:3333/get/10.1038/nature12373"
+    Then connect with http mode:
+      crossref-local --http search "CRISPR"
+      curl "http://localhost:8333/works?q=CRISPR&limit=10"
     """
     try:
         from .server import run_server

crossref_local/cli_cache.py

@@ -0,0 +1,179 @@
+"""CLI commands for cache management.
+
+This module provides cache-related CLI commands that are registered
+with the main CLI application.
+"""
+
+import json
+import click
+
+
+def register_cache_commands(cli_group):
+    """Register cache commands with the CLI group."""
+
+    @cli_group.group()
+    def cache():
+        """Manage paper caches for efficient querying."""
+        pass
+
+    @cache.command("create")
+    @click.argument("name")
+    @click.option("-q", "--query", required=True, help="FTS search query")
+    @click.option("-l", "--limit", default=1000, help="Max papers to cache")
+    @click.option("--json", "as_json", is_flag=True, help="Output as JSON")
+    def cache_create(name, query, limit, as_json):
+        """Create a cache from search query.
+
+        Example:
+            crossref-local cache create epilepsy -q "epilepsy seizure" -l 500
+        """
+        from . import cache as cache_module
+
+        info = cache_module.create(name, query=query, limit=limit)
+        if as_json:
+            click.echo(json.dumps(info.to_dict(), indent=2))
+        else:
+            click.echo(f"Created cache: {info.name}")
+            click.echo(f"  Papers: {info.paper_count}")
+            click.echo(f"  Size: {info.size_bytes / 1024 / 1024:.2f} MB")
+            click.echo(f"  Path: {info.path}")
+
+    @cache.command("list")
+    @click.option("--json", "as_json", is_flag=True, help="Output as JSON")
+    def cache_list(as_json):
+        """List all available caches."""
+        from . import cache as cache_module
+
+        caches = cache_module.list_caches()
+        if as_json:
+            click.echo(json.dumps([c.to_dict() for c in caches], indent=2))
+        else:
+            if not caches:
+                click.echo("No caches found.")
+                return
+            for c in caches:
+                click.echo(
+                    f"{c.name}: {c.paper_count} papers, {c.size_bytes / 1024 / 1024:.2f} MB"
+                )
+
+    @cache.command("query")
+    @click.argument("name")
+    @click.option("-f", "--fields", help="Comma-separated field list")
+    @click.option("--abstract", is_flag=True, help="Include abstracts")
+    @click.option("--refs", is_flag=True, help="Include references")
+    @click.option("--citations", is_flag=True, help="Include citation counts")
+    @click.option("--year-min", type=int, help="Minimum year filter")
+    @click.option("--year-max", type=int, help="Maximum year filter")
+    @click.option("--journal", help="Journal name filter")
+    @click.option("-l", "--limit", type=int, help="Max results")
+    @click.option("--json", "as_json", is_flag=True, help="Output as JSON")
+    def cache_query(
+        name,
+        fields,
+        abstract,
+        refs,
+        citations,
+        year_min,
+        year_max,
+        journal,
+        limit,
+        as_json,
+    ):
+        """Query cache with field filtering.
+
+        Examples:
+            crossref-local cache query epilepsy -f doi,title,year
+            crossref-local cache query epilepsy --year-min 2020 --citations
+        """
+        from . import cache as cache_module
+
+        field_list = fields.split(",") if fields else None
+        papers = cache_module.query(
+            name,
+            fields=field_list,
+            include_abstract=abstract,
+            include_references=refs,
+            include_citations=citations,
+            year_min=year_min,
+            year_max=year_max,
+            journal=journal,
+            limit=limit,
+        )
+
+        if as_json:
+            click.echo(json.dumps(papers, indent=2))
+        else:
+            click.echo(f"Found {len(papers)} papers")
+            for p in papers[:10]:
+                title = p.get("title", "No title")[:60]
+                year = p.get("year", "?")
+                click.echo(f"  [{year}] {title}...")
+            if len(papers) > 10:
+                click.echo(f"  ... and {len(papers) - 10} more")
+
+    @cache.command("stats")
+    @click.argument("name")
+    @click.option("--json", "as_json", is_flag=True, help="Output as JSON")
+    def cache_stats(name, as_json):
+        """Show cache statistics."""
+        from . import cache as cache_module
+
+        stats = cache_module.stats(name)
+        if as_json:
+            click.echo(json.dumps(stats, indent=2))
+        else:
+            click.echo(f"Papers: {stats['paper_count']}")
+            yr = stats.get("year_range", {})
+            click.echo(f"Years: {yr.get('min', '?')} - {yr.get('max', '?')}")
+            click.echo(f"Abstracts: {stats['abstract_coverage']}%")
+            click.echo("\nTop journals:")
+            for j in stats.get("top_journals", [])[:5]:
+                click.echo(f"  {j['journal']}: {j['count']}")
+
+    @cache.command("export")
+    @click.argument("name")
+    @click.argument("output")
+    @click.option(
+        "--format", "fmt", default="json", help="Format: json, csv, bibtex, dois"
+    )
+    @click.option("-f", "--fields", help="Comma-separated field list")
+    def cache_export(name, output, fmt, fields):
+        """Export cache to file.
+
+        Examples:
+            crossref-local cache export epilepsy papers.csv --format csv
+            crossref-local cache export epilepsy refs.bib --format bibtex
+        """
+        from . import cache as cache_module
+
+        field_list = fields.split(",") if fields else None
+        path = cache_module.export(name, output, format=fmt, fields=field_list)
+        click.echo(f"Exported to: {path}")
+
+    @cache.command("delete")
+    @click.argument("name")
+    @click.option("--yes", is_flag=True, help="Skip confirmation")
+    def cache_delete(name, yes):
+        """Delete a cache."""
+        from . import cache as cache_module
+
+        if not yes:
+            if not click.confirm(f"Delete cache '{name}'?"):
+                return
+
+        if cache_module.delete(name):
+            click.echo(f"Deleted: {name}")
+        else:
+            click.echo(f"Cache not found: {name}")
+
+    @cache.command("dois")
+    @click.argument("name")
+    def cache_dois(name):
+        """Output DOIs from cache (one per line)."""
+        from . import cache as cache_module
+
+        dois = cache_module.query_dois(name)
+        for doi in dois:
+            click.echo(doi)
+
+    return cache