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

openalex_local/__init__.py

@@ -8,7 +8,37 @@ Example:
     >>> work = get("10.1038/nature12373")  # or DOI
 """
 
-__version__ = "0.1.0"
+__version__ = "0.3.0"
 
-# API will be exposed here after implementation
-# from .api import search, get, count, info
+from .api import (
+    Config,
+    SearchResult,
+    Work,
+    configure,
+    configure_http,
+    count,
+    exists,
+    get,
+    get_many,
+    get_mode,
+    info,
+    search,
+)
+
+__all__ = [
+    # Core functions
+    "search",
+    "count",
+    "get",
+    "get_many",
+    "exists",
+    "info",
+    # Configuration
+    "configure",
+    "configure_http",
+    "get_mode",
+    # Classes
+    "Work",
+    "SearchResult",
+    "Config",
+]

openalex_local/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running as python -m openalex_local."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    main()

openalex_local/api.py

@@ -0,0 +1,258 @@
+"""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__ = [
+    "search",
+    "count",
+    "get",
+    "get_many",
+    "exists",
+    "configure",
+    "configure_http",
+    "get_mode",
+    "info",
+    "Work",
+    "SearchResult",
+    "Config",
+]
+
+
+def _get_http_client():
+    """Get HTTP client (lazy import to avoid circular dependency)."""
+    try:
+        from .remote import RemoteClient
+
+        return RemoteClient(Config.get_api_url())
+    except ImportError:
+        raise NotImplementedError(
+            "HTTP mode not yet implemented. Use database mode by setting "
+            "OPENALEX_LOCAL_DB environment variable."
+        )
+
+
+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
+    row = db.fetchone("SELECT COUNT(*) as count FROM works")
+    work_count = row["count"] if row else 0
+
+    # Get FTS count
+    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 {
+        "status": "ok",
+        "mode": "db",
+        "db_path": str(Config.get_db_path()),
+        "work_count": work_count,
+        "fts_indexed": fts_count,
+    }

openalex_local/cli.py

@@ -0,0 +1,209 @@
+#!/usr/bin/env python3
+"""CLI for openalex_local."""
+
+import json
+import sys
+
+import click
+
+from . import __version__
+
+
+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."""
+        click.secho(f"\n━━━ {prefix} ━━━", fg="cyan", bold=True)
+        sub_ctx = click.Context(cmd, info_name=prefix.split()[-1], parent=parent_ctx)
+        click.echo(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
+    click.secho("━━━ openalex-local ━━━", fg="cyan", bold=True)
+    click.echo(ctx.get_help())
+
+    # Print all subcommands recursively
+    for name, cmd in sorted(cli.commands.items()):
+        _print_command_help(cmd, f"openalex-local {name}", ctx)
+
+    ctx.exit(0)
+
+
+@click.group(context_settings={"help_option_names": ["-h", "--help"]})
+@click.version_option(__version__, "--version")
+@click.option("--http", is_flag=True, help="Use HTTP API instead of direct database")
+@click.option("--api-url", help="API URL for http mode (default: auto-detect)")
+@click.option(
+    "--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, http, api_url):
+    """
+    Local OpenAlex database with 284M+ works and full-text search.
+
+    \b
+    Supports both direct database access (db mode) and HTTP API (http mode).
+
+    \b
+    DB mode (default if database found):
+      openalex-local search "machine learning"
+
+    \b
+    HTTP mode (connect to API server):
+      openalex-local --http search "machine learning"
+    """
+    ctx.ensure_object(dict)
+
+    if http or api_url:
+        from . import configure_http
+
+        configure_http(api_url or "http://localhost:31292")
+
+
+@cli.command("search")
+@click.argument("query")
+@click.option("-n", "--number", default=10, 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("--concepts", is_flag=True, help="Show concepts/topics")
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON")
+def search_cmd(query, number, offset, abstracts, authors, concepts, as_json):
+    """Search for works by title, abstract, or authors."""
+    from . import search
+
+    try:
+        results = search(query, limit=number, offset=offset)
+    except FileNotFoundError as e:
+        click.secho(f"Error: {e}", fg="red", err=True)
+        sys.exit(1)
+
+    if as_json:
+        output = {
+            "query": query,
+            "total": results.total,
+            "elapsed_ms": results.elapsed_ms,
+            "works": [w.to_dict() for w in results.works],
+        }
+        click.echo(json.dumps(output, indent=2))
+        return
+
+    click.secho(
+        f"Found {results.total:,} matches in {results.elapsed_ms:.1f}ms\n",
+        fg="green",
+    )
+
+    for i, work in enumerate(results.works, 1):
+        click.secho(f"{i}. {work.title} ({work.year})", fg="cyan", bold=True)
+        click.echo(f"   DOI: {work.doi or 'N/A'}")
+        click.echo(f"   Journal: {work.source or 'N/A'}")
+
+        if authors and work.authors:
+            author_str = ", ".join(work.authors[:5])
+            if len(work.authors) > 5:
+                author_str += f" (+{len(work.authors) - 5} more)"
+            click.echo(f"   Authors: {author_str}")
+
+        if abstracts and work.abstract:
+            abstract = work.abstract[:300]
+            if len(work.abstract) > 300:
+                abstract += "..."
+            click.echo(f"   Abstract: {abstract}")
+
+        if concepts and work.concepts:
+            concept_names = [c.get("name", "") for c in work.concepts[:5]]
+            click.echo(f"   Concepts: {', '.join(concept_names)}")
+
+        click.echo()
+
+
+@cli.command("search-by-doi")
+@click.argument("doi")
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON")
+def search_by_doi_cmd(doi, as_json):
+    """Search for a work by DOI."""
+    from . import get
+
+    try:
+        work = get(doi)
+    except FileNotFoundError as e:
+        click.secho(f"Error: {e}", fg="red", err=True)
+        sys.exit(1)
+
+    if work is None:
+        click.secho(f"Not found: {doi}", fg="red", err=True)
+        sys.exit(1)
+
+    if as_json:
+        click.echo(json.dumps(work.to_dict(), indent=2))
+        return
+
+    click.secho(work.title, fg="cyan", bold=True)
+    click.echo(f"DOI: {work.doi}")
+    click.echo(f"OpenAlex ID: {work.openalex_id}")
+    click.echo(f"Year: {work.year or 'N/A'}")
+    click.echo(f"Journal: {work.source or 'N/A'}")
+    click.echo(f"Type: {work.type or 'N/A'}")
+    click.echo(f"Citations: {work.cited_by_count or 0}")
+
+    if work.authors:
+        click.echo(f"Authors: {', '.join(work.authors)}")
+
+    if work.abstract:
+        click.echo(f"\nAbstract:\n{work.abstract}")
+
+    if work.is_oa and work.oa_url:
+        click.echo(f"\nOpen Access: {work.oa_url}")
+
+
+@cli.command("status")
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON")
+def status_cmd(as_json):
+    """Show status and configuration."""
+    from . import info
+
+    try:
+        status = info()
+    except FileNotFoundError as e:
+        if as_json:
+            click.echo(json.dumps({"status": "error", "error": str(e)}, indent=2))
+        else:
+            click.secho(f"Error: {e}", fg="red", err=True)
+        sys.exit(1)
+
+    if as_json:
+        click.echo(json.dumps(status, indent=2))
+        return
+
+    click.secho("OpenAlex Local Status", fg="cyan", bold=True)
+    click.echo(f"Mode: {status.get('mode', 'unknown')}")
+    click.echo(f"Status: {status.get('status', 'unknown')}")
+
+    if "db_path" in status:
+        click.echo(f"Database: {status['db_path']}")
+
+    if "work_count" in status:
+        click.echo(f"Works: {status['work_count']:,}")
+
+    if "fts_indexed" in status:
+        click.echo(f"FTS Indexed: {status['fts_indexed']:,}")
+
+
+def main():
+    """Entry point for CLI."""
+    cli()
+
+
+if __name__ == "__main__":
+    main()

openalex_local/config.py

@@ -47,10 +47,19 @@ def get_db_path() -> Path:
     )
 
 
+# Default port (SciTeX port scheme: 31292 for openalex)
+DEFAULT_PORT = 31292
+DEFAULT_HOST = "0.0.0.0"
+
+
 class Config:
     """Configuration container."""
 
     _db_path: Optional[Path] = None
+    _api_url: Optional[str] = None
+    _mode: Optional[str] = None  # "db" or "http"
+    _port: Optional[int] = None
+    _host: Optional[str] = None
 
     @classmethod
     def get_db_path(cls) -> Path:
@@ -66,8 +75,108 @@ class Config:
         if not path.exists():
             raise FileNotFoundError(f"Database not found: {path}")
         cls._db_path = path
+        cls._mode = "db"
+
+    @classmethod
+    def get_api_url(cls) -> str:
+        """Get API URL for HTTP mode."""
+        if cls._api_url:
+            return cls._api_url
+
+        # Check environment variables (scitex priority)
+        for var in [
+            "SCITEX_SCHOLAR_OPENALEX_API_URL",
+            "OPENALEX_LOCAL_API_URL",
+        ]:
+            url = os.environ.get(var)
+            if url:
+                return url
+
+        return "http://localhost:31292"
+
+    @classmethod
+    def set_api_url(cls, url: str) -> None:
+        """Set API URL explicitly."""
+        cls._api_url = url
+        cls._mode = "http"
+
+    @classmethod
+    def get_mode(cls) -> str:
+        """
+        Get current mode.
+
+        Priority:
+        1. Explicitly set mode
+        2. OPENALEX_LOCAL_MODE environment variable
+        3. Auto-detect based on available config
+
+        Returns:
+            "db" or "http"
+        """
+        if cls._mode:
+            return cls._mode
+
+        # Check environment variable
+        env_mode = os.environ.get("OPENALEX_LOCAL_MODE", "").lower()
+        if env_mode in ("db", "http"):
+            return env_mode
+
+        # Check if API URL is set
+        if os.environ.get("OPENALEX_LOCAL_API_URL"):
+            return "http"
+
+        # Default to db mode (will raise FileNotFoundError if no database)
+        return "db"
+
+    @classmethod
+    def get_port(cls) -> int:
+        """Get server port."""
+        if cls._port:
+            return cls._port
+
+        # Check environment variables (scitex priority)
+        for var in [
+            "SCITEX_SCHOLAR_OPENALEX_PORT",
+            "OPENALEX_LOCAL_PORT",
+        ]:
+            port = os.environ.get(var)
+            if port:
+                return int(port)
+
+        return DEFAULT_PORT
+
+    @classmethod
+    def set_port(cls, port: int) -> None:
+        """Set server port explicitly."""
+        cls._port = port
+
+    @classmethod
+    def get_host(cls) -> str:
+        """Get server host."""
+        if cls._host:
+            return cls._host
+
+        # Check environment variables (scitex priority)
+        for var in [
+            "SCITEX_SCHOLAR_OPENALEX_HOST",
+            "OPENALEX_LOCAL_HOST",
+        ]:
+            host = os.environ.get(var)
+            if host:
+                return host
+
+        return DEFAULT_HOST
+
+    @classmethod
+    def set_host(cls, host: str) -> None:
+        """Set server host explicitly."""
+        cls._host = host
 
     @classmethod
     def reset(cls) -> None:
         """Reset configuration (for testing)."""
         cls._db_path = None
+        cls._api_url = None
+        cls._mode = None
+        cls._port = None
+        cls._host = None

openalex_local/db.py

@@ -0,0 +1,161 @@
+"""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
+
+
+# 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()

openalex_local/fts.py

@@ -0,0 +1,165 @@
+"""Full-text search using FTS5."""
+
+import re as _re
+import time as _time
+from typing import List, Optional
+
+from .db import Database, get_db
+from .models import SearchResult, Work
+
+__all__ = [
+    "search",
+    "count",
+    "search_ids",
+]
+
+
+def _sanitize_query(query: str) -> str:
+    """
+    Sanitize query for FTS5.
+
+    Handles special characters that FTS5 interprets as operators.
+    """
+    if query.startswith('"') and query.endswith('"'):
+        return query
+
+    has_hyphenated_word = _re.search(r"\w+-\w+", query)
+    has_special = _re.search(r"[/\\@#$%^&]", query)
+
+    if has_hyphenated_word or has_special:
+        words = query.split()
+        quoted = " ".join(f'"{w}"' for w in words)
+        return quoted
+
+    return query
+
+
+def search(
+    query: str,
+    limit: int = 20,
+    offset: int = 0,
+    db: Optional[Database] = None,
+) -> SearchResult:
+    """
+    Full-text search across works.
+
+    Uses FTS5 index for fast searching across titles and abstracts.
+
+    Args:
+        query: Search query (supports FTS5 syntax like AND, OR, NOT, "phrases")
+        limit: Maximum results to return
+        offset: Skip first N results (for pagination)
+        db: Database connection (uses singleton if not provided)
+
+    Returns:
+        SearchResult with matching works
+
+    Example:
+        >>> results = search("machine learning neural networks")
+        >>> print(f"Found {results.total} matches in {results.elapsed_ms:.1f}ms")
+    """
+    if db is None:
+        db = get_db()
+
+    start = _time.perf_counter()
+    safe_query = _sanitize_query(query)
+
+    # Get total count
+    count_row = db.fetchone(
+        "SELECT COUNT(*) as total FROM works_fts WHERE works_fts MATCH ?",
+        (safe_query,),
+    )
+    total = count_row["total"] if count_row else 0
+
+    # Get matching works
+    rows = db.fetchall(
+        """
+        SELECT w.*
+        FROM works_fts f
+        JOIN works w ON f.rowid = w.rowid
+        WHERE works_fts MATCH ?
+        LIMIT ? OFFSET ?
+        """,
+        (safe_query, limit, offset),
+    )
+
+    elapsed_ms = (_time.perf_counter() - start) * 1000
+
+    # Convert to Work objects
+    works = []
+    for row in rows:
+        data = db._row_to_dict(row)
+        works.append(Work.from_db_row(data))
+
+    return SearchResult(
+        works=works,
+        total=total,
+        query=query,
+        elapsed_ms=elapsed_ms,
+    )
+
+
+def count(query: str, db: Optional[Database] = None) -> int:
+    """
+    Count matching works without fetching results.
+
+    Args:
+        query: FTS5 search query
+        db: Database connection
+
+    Returns:
+        Number of matching works
+    """
+    if db is None:
+        db = get_db()
+
+    safe_query = _sanitize_query(query)
+    row = db.fetchone(
+        "SELECT COUNT(*) as total FROM works_fts WHERE works_fts MATCH ?",
+        (safe_query,),
+    )
+    return row["total"] if row else 0
+
+
+def search_ids(
+    query: str,
+    limit: int = 1000,
+    db: Optional[Database] = None,
+) -> List[str]:
+    """
+    Search and return only OpenAlex IDs (faster than full search).
+
+    Args:
+        query: FTS5 search query
+        limit: Maximum IDs to return
+        db: Database connection
+
+    Returns:
+        List of matching OpenAlex IDs
+    """
+    if db is None:
+        db = get_db()
+
+    safe_query = _sanitize_query(query)
+    rows = db.fetchall(
+        """
+        SELECT w.openalex_id
+        FROM works_fts f
+        JOIN works w ON f.rowid = w.rowid
+        WHERE works_fts MATCH ?
+        LIMIT ?
+        """,
+        (safe_query, limit),
+    )
+
+    return [row["openalex_id"] for row in rows]
+
+
+def _search_with_db(db: Database, query: str, limit: int, offset: int) -> SearchResult:
+    """Search with explicit database connection (for thread-safe async)."""
+    return search(query, limit, offset, db=db)
+
+
+def _count_with_db(db: Database, query: str) -> int:
+    """Count with explicit database connection (for thread-safe async)."""
+    return count(query, db=db)

openalex_local/models.py

@@ -66,7 +66,11 @@ class Work:
         openalex_id = data.get("id", "").replace("https://openalex.org/", "")
 
         # Extract DOI
-        doi = data.get("doi", "").replace("https://doi.org/", "") if data.get("doi") else None
+        doi = (
+            data.get("doi", "").replace("https://doi.org/", "")
+            if data.get("doi")
+            else None
+        )
 
         # Extract authors
         authors = []
@@ -81,7 +85,11 @@ class Work:
         inv_index = data.get("abstract_inverted_index")
         if inv_index:
             words = sorted(
-                [(pos, word) for word, positions in inv_index.items() for pos in positions]
+                [
+                    (pos, word)
+                    for word, positions in inv_index.items()
+                    for pos in positions
+                ]
             )
             abstract = " ".join(word for _, word in words)
 
@@ -103,7 +111,10 @@ class Work:
 
         # Extract topics (top 3)
         topics = [
-            {"name": t.get("display_name"), "subfield": t.get("subfield", {}).get("display_name")}
+            {
+                "name": t.get("display_name"),
+                "subfield": t.get("subfield", {}).get("display_name"),
+            }
             for t in (data.get("topics") or [])[:3]
         ]
 
@@ -135,6 +146,39 @@ class Work:
             oa_url=oa_info.get("oa_url"),
         )
 
+    @classmethod
+    def from_db_row(cls, data: dict) -> "Work":
+        """
+        Create Work from database row dictionary.
+
+        Args:
+            data: Database row as dictionary (with parsed JSON fields)
+
+        Returns:
+            Work instance
+        """
+        return cls(
+            openalex_id=data.get("openalex_id", ""),
+            doi=data.get("doi"),
+            title=data.get("title"),
+            abstract=data.get("abstract"),
+            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"),
+            publisher=data.get("publisher"),
+            type=data.get("type"),
+            concepts=data.get("concepts", []),
+            topics=data.get("topics", []),
+            cited_by_count=data.get("cited_by_count"),
+            referenced_works=data.get("referenced_works", []),
+            is_oa=bool(data.get("is_oa", False)),
+            oa_url=data.get("oa_url"),
+        )
+
     def to_dict(self) -> dict:
         """Convert to dictionary."""
         return {

{openalex_local-0.1.0.dist-info → openalex_local-0.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openalex-local
-Version: 0.1.0
+Version: 0.3.0
 Summary: Local OpenAlex database with 284M+ works, abstracts, and semantic search
 Author-email: Yusuke Watanabe <ywatanabe@alumni.u-tokyo.ac.jp>
 License: AGPL-3.0

openalex_local-0.3.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+openalex_local/__init__.py,sha256=UKl7hQFZMwK1oPV3zz7V2Pw7M4ufPouUCNwmODdFZlw,759
+openalex_local/__main__.py,sha256=7zIPyOv659VptzHef3Zsw3k6m-WhGTN4MFq2-yVkdLE,111
+openalex_local/api.py,sha256=LRIU0JZ41c33YAK96r_MOHNP5tdweu1_Fd-ZRdZ8IT0,6036
+openalex_local/cli.py,sha256=LLlgdAdt6qrF1LVZf5jtimsDiTmvLQ-wzw0-hCnLbr0,6464
+openalex_local/config.py,sha256=pwvXj-CncHCWdQr4ZhtH4ItuDY7RVKWikspQYyYfcbE,4848
+openalex_local/db.py,sha256=eNPZ4Ejqn2w2m5Gk8eCApQHT_cr2X5wt4KiOeVeU7wU,4355
+openalex_local/fts.py,sha256=52TrRqabNj1zLR8gDtb9mOgIXioEBaTRJN7tz5mAcpE,3959
+openalex_local/models.py,sha256=yLjQsYgDcjvjqwt_amvIAXNTpGgcy8nqEkSS70Q8_cY,7120
+openalex_local-0.3.0.dist-info/METADATA,sha256=sL5zP_JOo9DRNcvgrX1myWczeCGnrtWhAJ78VLpuAWc,4384
+openalex_local-0.3.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+openalex_local-0.3.0.dist-info/entry_points.txt,sha256=OYO9RohYQ52zoeb-jTjhMYR07F0PioGQXPizMnBv_Es,59
+openalex_local-0.3.0.dist-info/top_level.txt,sha256=arEhuDR1f42p7soJ5JkJFAnAiCPSGKvuHIchaKTmqKg,15
+openalex_local-0.3.0.dist-info/RECORD,,

{openalex_local-0.1.0.dist-info → openalex_local-0.3.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.9.0)
+Generator: setuptools (80.10.2)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

openalex_local-0.1.0.dist-info/RECORD

@@ -1,8 +0,0 @@
-openalex_local/__init__.py,sha256=WwenwvcOpwFgb8bTZVtXKMOePQ5H4yWUXj2oGfUSsvY,422
-openalex_local/config.py,sha256=O8NNqgXbmXx_Frjh7DLdHZ88Y6Qo3TkKzVji4TFNLjo,2046
-openalex_local/models.py,sha256=rMDPNbeAw98tNAerOTA1WB_Ei73i-M4HTpp9N55vQPE,5837
-openalex_local-0.1.0.dist-info/METADATA,sha256=iq6ZDmV7-Hneq2UpZdWut8fUDPogThGvzkpN1E72cwE,4384
-openalex_local-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-openalex_local-0.1.0.dist-info/entry_points.txt,sha256=OYO9RohYQ52zoeb-jTjhMYR07F0PioGQXPizMnBv_Es,59
-openalex_local-0.1.0.dist-info/top_level.txt,sha256=arEhuDR1f42p7soJ5JkJFAnAiCPSGKvuHIchaKTmqKg,15
-openalex_local-0.1.0.dist-info/RECORD,,