genetinav 0.1.0__py3-none-any.whl

genetinav/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

genetinav/api_client.py

@@ -0,0 +1,124 @@
+import httpx
+from typing import Optional, Dict
+
+from genetinav.utils.errors import (
+    GeneNotFoundError,
+    NetworkUnavailableError,
+    ApiRateLimitError,
+    SequenceFetchError,
+)
+
+class EnsemblClient:
+    def __init__(self, base_url: str = "https://rest.ensembl.org", timeout: float = 10.0):
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self._client: Optional[httpx.Client] = None
+
+    @property
+    def client(self) -> httpx.Client:
+        if self._client is None:
+            self._client = httpx.Client(timeout=self.timeout)
+        return self._client
+
+    def close(self) -> None:
+        if self._client is not None:
+            self._client.close()
+            self._client = None
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()
+
+    def _handle_exceptions(self, response: httpx.Response, symbol_or_region: str):
+        if response.status_code == 404:
+            raise GeneNotFoundError(f"No gene found for '{symbol_or_region}'.")
+        elif response.status_code == 400:
+            raise GeneNotFoundError(f"Bad request or out of bounds for '{symbol_or_region}'.")
+        elif response.status_code == 429:
+            raise ApiRateLimitError("API rate limit exceeded.")
+        elif not response.is_success:
+            raise SequenceFetchError(f"API request failed with status code {response.status_code}.")
+
+    def lookup_gene(self, symbol: str, species: str = "human") -> dict:
+        url = f"{self.base_url}/lookup/symbol/{species}/{symbol}?content-type=application/json"
+        
+        try:
+            response = self.client.get(url)
+        except (httpx.ConnectError, httpx.TimeoutException) as e:
+            raise NetworkUnavailableError(f"Network error: {e}") from e
+
+        self._handle_exceptions(response, symbol)
+
+        return response.json()
+
+    def fetch_sequence(self, region: str, species: str = "human") -> str:
+        url = f"{self.base_url}/sequence/region/{species}/{region}?content-type=text/plain"
+        
+        try:
+            response = self.client.get(url)
+        except (httpx.ConnectError, httpx.TimeoutException) as e:
+            raise NetworkUnavailableError(f"Network error: {e}") from e
+
+        self._handle_exceptions(response, region)
+
+        # Strip all whitespace/newlines from the sequence
+        return "".join(response.text.split())
+
+    def lookup_gene_by_id(self, gene_id: str) -> dict:
+        url = f"{self.base_url}/lookup/id/{gene_id}?expand=1&content-type=application/json"
+        
+        try:
+            response = self.client.get(url)
+        except (httpx.ConnectError, httpx.TimeoutException) as e:
+            raise NetworkUnavailableError(f"Network error: {e}") from e
+
+        self._handle_exceptions(response, gene_id)
+
+        return response.json()
+
+    def overlap_genes(self, chromosome: str, start: int, end: int, species: str = "human") -> list[dict]:
+        """Return a list of genes overlapping the given genomic range.
+
+        Queries ``GET /overlap/region/{species}/{chromosome}:{start}-{end}?feature=gene``
+        and returns the raw JSON list (each element has at least ``external_name``,
+        ``start``, ``end``, ``strand``, and ``id`` fields).
+
+        Returns an empty list on 404 / out-of-bounds rather than raising.
+        """
+        url = (
+            f"{self.base_url}/overlap/region/{species}/{chromosome}:{start}-{end}"
+            f"?feature=gene&content-type=application/json"
+        )
+        try:
+            response = self.client.get(url)
+        except (httpx.ConnectError, httpx.TimeoutException) as e:
+            raise NetworkUnavailableError(f"Network error: {e}") from e
+
+        if response.status_code == 404 or response.status_code == 400:
+            return []
+        elif response.status_code == 429:
+            raise ApiRateLimitError("API rate limit exceeded.")
+        elif not response.is_success:
+            raise SequenceFetchError(f"API request failed with status code {response.status_code}.")
+
+        data = response.json()
+        # The endpoint returns either a list or an error dict
+        if isinstance(data, list):
+            return data
+        return []
+
+    def fetch_transcript_sequence(self, transcript_id: str, is_cds: bool = False) -> str:
+        seq_type = "cds" if is_cds else "cdna"
+        url = f"{self.base_url}/sequence/id/{transcript_id}?type={seq_type}&content-type=text/plain"
+        
+        try:
+            response = self.client.get(url)
+        except (httpx.ConnectError, httpx.TimeoutException) as e:
+            raise NetworkUnavailableError(f"Network error: {e}") from e
+
+        self._handle_exceptions(response, transcript_id)
+
+        # Strip all whitespace/newlines from the sequence
+        return "".join(response.text.split())

genetinav/cache.py

@@ -0,0 +1,71 @@
+import datetime
+import sqlite3
+
+from genetinav.db import get_connection, initialize_schema
+from genetinav.utils.errors import CacheError
+
+class CacheManager:
+    def __init__(self, conn: sqlite3.Connection):
+        self.conn = conn
+        initialize_schema(self.conn)
+
+    def set(self, key: str, response_data: str, ttl_seconds: int | None = None) -> None:
+        try:
+            now = datetime.datetime.now(datetime.timezone.utc)
+            created_at = now.isoformat()
+            
+            if ttl_seconds is not None:
+                expires_at = (now + datetime.timedelta(seconds=ttl_seconds)).isoformat()
+            else:
+                expires_at = None
+                
+            self.conn.execute(
+                """
+                INSERT INTO cache (key, response_data, created_at, expires_at)
+                VALUES (?, ?, ?, ?)
+                ON CONFLICT(key) DO UPDATE SET
+                    response_data=excluded.response_data,
+                    created_at=excluded.created_at,
+                    expires_at=excluded.expires_at
+                """,
+                (key, response_data, created_at, expires_at)
+            )
+            self.conn.commit()
+        except sqlite3.Error as e:
+            raise CacheError(f"Cache read/write failed: {e}") from e
+
+    def get(self, key: str) -> str | None:
+        try:
+            now_iso = datetime.datetime.now(datetime.timezone.utc).isoformat()
+            
+            cursor = self.conn.execute(
+                "SELECT response_data, expires_at FROM cache WHERE key = ?",
+                (key,)
+            )
+            row = cursor.fetchone()
+            
+            if row is None:
+                return None
+                
+            expires_at = row["expires_at"]
+            if expires_at is not None and expires_at <= now_iso:
+                self.delete(key)
+                return None
+                
+            return row["response_data"]
+        except sqlite3.Error as e:
+            raise CacheError(f"Cache read/write failed: {e}") from e
+
+    def clear(self) -> None:
+        try:
+            self.conn.execute("DELETE FROM cache")
+            self.conn.commit()
+        except sqlite3.Error as e:
+            raise CacheError(f"Cache read/write failed: {e}") from e
+
+    def delete(self, key: str) -> None:
+        try:
+            self.conn.execute("DELETE FROM cache WHERE key = ?", (key,))
+            self.conn.commit()
+        except sqlite3.Error as e:
+            raise CacheError(f"Cache read/write failed: {e}") from e

genetinav/chunk_cache.py

@@ -0,0 +1,148 @@
+import threading
+from collections import OrderedDict
+from concurrent.futures import ThreadPoolExecutor
+from typing import Optional
+
+from genetinav.api_client import EnsemblClient
+from genetinav.utils.errors import GeneNotFoundError, NetworkUnavailableError, SequenceFetchError
+
+
+class ChunkCache:
+    def __init__(self, api_client: EnsemblClient, chunk_size: int = 5000, max_chunks: int = 100):
+        self.api_client = api_client
+        self.chunk_size = chunk_size
+        self.max_chunks = max_chunks
+        
+        self._cache: OrderedDict[tuple[str, str, int], str] = OrderedDict()
+        self._lock = threading.Lock()
+        self._executor = ThreadPoolExecutor(max_workers=3)
+        self._fetching: set[tuple[str, str, int]] = set()
+        self._errors: dict[tuple[str, str], Exception] = {}
+
+    def get_chunk_start(self, coord: int) -> int:
+        """Ensembl coordinates are 1-indexed. We align to chunk_size boundaries.
+        Example for chunk_size=5000:
+        coord=1 -> 1
+        coord=5000 -> 1
+        coord=5001 -> 5001
+        """
+        return ((coord - 1) // self.chunk_size) * self.chunk_size + 1
+
+    def get_sequence_slice(self, species: str, chromosome: str, start_coord: int, end_coord: int) -> Optional[str]:
+        """
+        Returns the sequence string if fully cached, else None.
+        start_coord and end_coord are absolute 1-indexed coordinates.
+        end_coord is inclusive.
+        """
+        req_chunks = []
+        c_start = self.get_chunk_start(start_coord)
+        while c_start <= end_coord:
+            req_chunks.append(c_start)
+            c_start += self.chunk_size
+            
+        with self._lock:
+            for c in req_chunks:
+                key = (species, chromosome, c)
+                if key not in self._cache:
+                    return None
+                    
+            pieces = []
+            for c in req_chunks:
+                key = (species, chromosome, c)
+                self._cache.move_to_end(key)
+                pieces.append(self._cache[key])
+                
+        full_str = "".join(pieces)
+        
+        # Calculate offsets into the joined string
+        first_chunk_start = req_chunks[0]
+        offset_start = start_coord - first_chunk_start
+        length = end_coord - start_coord + 1
+        
+        return full_str[offset_start : offset_start + length]
+
+    def fetch_blocking(self, species: str, chromosome: str, start_coord: int, end_coord: int) -> str:
+        """Synchronously fetches missing chunks for the requested range, returns the slice."""
+        req_chunks = []
+        c_start = self.get_chunk_start(start_coord)
+        while c_start <= end_coord:
+            req_chunks.append(c_start)
+            c_start += self.chunk_size
+            
+        for c in req_chunks:
+            key = (species, chromosome, c)
+            with self._lock:
+                if key in self._cache:
+                    continue
+            self._fetch_chunk(species, chromosome, c)
+            
+        # Clear any recent errors for this species/chrom since we succeeded
+        with self._lock:
+            self._errors.pop((species, chromosome), None)
+            
+        res = self.get_sequence_slice(species, chromosome, start_coord, end_coord)
+        if res is None:
+            # Fallback if something went extremely wrong, shouldn't happen.
+            return "N" * (end_coord - start_coord + 1)
+        return res
+
+    def prefetch(self, species: str, chromosome: str, start_coord: int, end_coord: int) -> None:
+        """Kicks off background fetch for the view and its neighbors."""
+        current_c = self.get_chunk_start(start_coord)
+        
+        chunks_to_fetch = [
+            current_c - self.chunk_size,
+            current_c,
+            current_c + self.chunk_size,
+            current_c + 2 * self.chunk_size,
+            current_c + 3 * self.chunk_size
+        ]
+        
+        for c in chunks_to_fetch:
+            if c < 1:
+                continue
+            key = (species, chromosome, c)
+            with self._lock:
+                if key in self._cache or key in self._fetching:
+                    continue
+                self._fetching.add(key)
+                
+            self._executor.submit(self._fetch_chunk_bg, species, chromosome, c)
+
+    def _fetch_chunk_bg(self, species: str, chromosome: str, chunk_start: int) -> None:
+        try:
+            self._fetch_chunk(species, chromosome, chunk_start)
+        except Exception as e:
+            # Store error so it can be surfaced non-fatally
+            with self._lock:
+                self._errors[(species, chromosome)] = e
+        finally:
+            with self._lock:
+                self._fetching.discard((species, chromosome, chunk_start))
+
+    def _fetch_chunk(self, species: str, chromosome: str, chunk_start: int) -> None:
+        chunk_end = chunk_start + self.chunk_size - 1
+        region = f"{chromosome}:{chunk_start}..{chunk_end}"
+        try:
+            seq = self.api_client.fetch_sequence(region, species=species)
+        except GeneNotFoundError:
+            # Region is completely out of bounds or missing. Pad entirely with Ns.
+            seq = ""
+            
+        expected_len = self.chunk_size
+        if len(seq) < expected_len:
+            seq += "N" * (expected_len - len(seq))
+            
+        with self._lock:
+            key = (species, chromosome, chunk_start)
+            self._cache[key] = seq
+            if len(self._cache) > self.max_chunks:
+                self._cache.popitem(last=False)
+
+    def get_latest_error(self, species: str, chromosome: str) -> Optional[Exception]:
+        with self._lock:
+            return self._errors.get((species, chromosome))
+
+    def get_cached_bytes(self) -> int:
+        with self._lock:
+            return len(self._cache) * self.chunk_size

genetinav/cli.py

@@ -0,0 +1,239 @@
+"""Command-line interface for GenetiNav.
+
+Quick-command flags (spec Section 25):
+  genetinav                       # launch interactive TUI
+  genetinav <GENE>                # quick gene lookup, then exit
+  genetinav search <GENE>         # launch TUI pre-filled with GENE
+  genetinav settings              # open settings screen then exit
+  genetinav --no-animation        # disable animations for this session
+  genetinav --theme <NAME>        # override active palette for this session
+  genetinav --species <NAME>      # override default species for this session
+  genetinav --clear-cache         # clear local gene cache then exit
+  genetinav --clear-history       # clear search history then exit
+  genetinav --version             # print version and exit
+"""
+
+import typer
+from typing import Optional
+
+from genetinav import __version__
+from genetinav.cache import CacheManager
+from genetinav.history import HistoryManager
+from genetinav.db import get_connection, initialize_schema
+
+
+class DefaultGroup(typer.core.TyperGroup):
+    """Allow a bare positional argument to be handled as the 'default' sub-command."""
+
+    def resolve_command(self, ctx, args):
+        if args and args[0] not in self.commands and not args[0].startswith("-"):
+            args.insert(0, "default")
+        return super().resolve_command(ctx, args)
+
+
+app = typer.Typer(cls=DefaultGroup)
+
+
+def version_callback(value: bool):
+    if value:
+        typer.echo(f"genetinav v{__version__}")
+        raise typer.Exit()
+
+
+def _build_overrides(
+    no_animation: bool,
+    theme: Optional[str],
+    species: Optional[str],
+) -> dict:
+    """Return a partial settings dict reflecting CLI flag overrides."""
+    overrides: dict = {}
+    if no_animation:
+        overrides["performance_mode"] = True
+        overrides["animations_enabled"] = False
+        overrides["splash_animation_enabled"] = False
+    if theme:
+        overrides["theme"] = theme
+    if species:
+        overrides["default_species"] = species
+    return overrides
+
+
+
+
+
+def _validate_cli_overrides(theme: Optional[str], species: Optional[str]) -> None:
+    """Validate --theme and --species values at the CLI boundary.
+
+    Prints a user-friendly error and raises ``typer.Exit(code=1)`` when an
+    invalid value is supplied, so the error surfaces before GenetinavApp is
+    ever constructed or the database is touched.
+    """
+    if theme is not None:
+        from genetinav.themes import list_ui_theme_names
+        valid_themes = list_ui_theme_names()
+        if theme not in valid_themes:
+            typer.echo(
+                f"Error: '{theme}' is not a valid theme. "
+                f"Valid themes: {', '.join(valid_themes)}"
+            )
+            raise typer.Exit(code=1)
+
+    if species is not None:
+        from genetinav.utils.validation import DEFAULT_ALLOWED_SPECIES
+        valid_species = DEFAULT_ALLOWED_SPECIES
+        normalized = species.strip().lower()
+        if normalized not in valid_species:
+            typer.echo(
+                f"Error: '{species}' is not a valid species. "
+                f"Valid species: {', '.join(valid_species)}"
+            )
+            raise typer.Exit(code=1)
+
+
+def _run_gene_cmd(
+    gene: str,
+    no_animation: bool,
+    theme: Optional[str],
+    species: Optional[str],
+    echo_message: str,
+) -> None:
+    """Shared implementation for default_cmd and search_cmd.
+
+    Validates overrides, emits the command-specific banner, constructs the
+    app, and runs the quick-lookup flow.  Each caller supplies its own
+    *echo_message* ("Quick lookup: {gene}" vs "Searching for: {gene}").
+    """
+    _validate_cli_overrides(theme, species)
+    typer.echo(echo_message)
+    overrides = _build_overrides(no_animation, theme, species)
+    from genetinav.settings import load_settings
+    from genetinav.textual_app import GenetinavTUI
+    
+    settings = load_settings()
+    settings.update(overrides)
+    tui = GenetinavTUI(settings=settings, initial_query=gene)
+    tui.run()
+    typer.echo("Session terminated gracefully. Goodbye!")
+
+
+@app.callback(invoke_without_command=True)
+def cli(
+    ctx: typer.Context,
+    version: Optional[bool] = typer.Option(
+        None,
+        "--version",
+        callback=version_callback,
+        is_eager=True,
+        help="Show the version and exit.",
+    ),
+    no_animation: bool = typer.Option(False, "--no-animation", help="Disable animations for this session"),
+    theme: Optional[str] = typer.Option(None, "--theme", help="Override active colour palette"),
+    species: Optional[str] = typer.Option(None, "--species", help="Override default species"),
+    clear_cache: bool = typer.Option(False, "--clear-cache", help="Clear the local gene cache then exit"),
+    clear_history: bool = typer.Option(False, "--clear-history", help="Clear the search history then exit"),
+) -> None:
+    """GenetiNav — navigational genomics toolkit."""
+
+    # --clear-cache / --clear-history are handled first so they can be combined
+    # with each other (and still print their confirmation messages) before any
+    # interactive UI is launched.
+    if clear_cache:
+        conn = get_connection()
+        initialize_schema(conn)
+        cache_mgr = CacheManager(conn)
+        cache_mgr.clear()
+        conn.close()
+        typer.echo("Cache cleared")
+
+    if clear_history:
+        conn = get_connection()
+        initialize_schema(conn)
+        history_mgr = HistoryManager(conn)
+        history_mgr.clear()
+        conn.close()
+        typer.echo("History cleared")
+
+    # If a data-clearing flag was used without a subcommand, exit cleanly.
+    if clear_cache or clear_history:
+        if ctx.invoked_subcommand is None:
+            return
+
+    # Launch the interactive TUI when no subcommand was given.
+    # Informational flag summaries are printed *after* the session ends so
+    # they are not immediately scrolled away by the splash screen.
+    if ctx.invoked_subcommand is None:
+        overrides = _build_overrides(no_animation, theme, species)
+        from genetinav.settings import load_settings
+        from genetinav.textual_app import GenetinavTUI
+        settings = load_settings()
+        settings.update(overrides)
+        tui = GenetinavTUI(settings=settings)
+        tui.run()
+        typer.echo("Session terminated gracefully. Goodbye!")
+
+        # Print flag confirmations after the TUI exits so they remain visible.
+        if no_animation:
+            typer.echo("Performance mode enabled")
+        if theme:
+            typer.echo(f"Theme set to: {theme}")
+        if species:
+            typer.echo(f"Species set to: {species}")
+
+
+@app.command("default", hidden=True)
+def default_cmd(
+    gene: str,
+    no_animation: bool = typer.Option(False, "--no-animation"),
+    theme: Optional[str] = typer.Option(None, "--theme"),
+    species: Optional[str] = typer.Option(None, "--species"),
+) -> None:
+    """Quick lookup: launch TUI pre-filled with GENE."""
+    _run_gene_cmd(
+        gene=gene,
+        no_animation=no_animation,
+        theme=theme,
+        species=species,
+        echo_message=f"Quick lookup: {gene.upper()}",
+    )
+
+
+@app.command("search")
+def search_cmd(
+    gene: str,
+    no_animation: bool = typer.Option(False, "--no-animation"),
+    theme: Optional[str] = typer.Option(None, "--theme"),
+    species: Optional[str] = typer.Option(None, "--species"),
+) -> None:
+    """Search for a GENE in the interactive TUI."""
+    _run_gene_cmd(
+        gene=gene,
+        no_animation=no_animation,
+        theme=theme,
+        species=species,
+        echo_message=f"Searching for: {gene.upper()}",
+    )
+
+
+@app.command("settings")
+def settings_cmd(
+    no_animation: bool = typer.Option(False, "--no-animation"),
+    theme: Optional[str] = typer.Option(None, "--theme"),
+) -> None:
+    """Open the settings screen."""
+    overrides = _build_overrides(no_animation, theme, None)
+    from genetinav.settings import load_settings
+    from genetinav.textual_app import GenetinavTUI
+    
+    settings = load_settings()
+    settings.update(overrides)
+    tui = GenetinavTUI(settings=settings, initial_screen="settings")
+    tui.run()
+    typer.echo("Session terminated gracefully. Goodbye!")
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

genetinav/command_parser.py

@@ -0,0 +1,32 @@
+def parse_command(input_str: str, valid_commands: list[str] | None = None) -> tuple[str | None, str, str | None]:
+    """Parse a slash command or return as a raw query.
+    
+    Returns:
+        (command_name, arguments, error_message)
+    """
+    s = input_str.strip()
+    if not s:
+        return None, "", None
+        
+    if s.startswith("/"):
+        parts = s[1:].split(" ", 1)
+        raw_cmd = parts[0].strip().lower()
+        args = parts[1].strip() if len(parts) > 1 else ""
+        
+        if valid_commands is not None and raw_cmd:
+            if raw_cmd in valid_commands:
+                return raw_cmd, args, None
+                
+            prefix_matches = [cmd for cmd in valid_commands if cmd.startswith(raw_cmd)]
+            
+            if len(prefix_matches) == 1:
+                return prefix_matches[0], args, None
+            elif len(prefix_matches) > 1:
+                pick_list = " ".join(f"{i+1}) /{cmd}" for i, cmd in enumerate(prefix_matches))
+                return None, "", f"Ambiguous command. Did you mean: {pick_list}"
+            else:
+                return None, "", f"Unknown command: /{raw_cmd}"
+                
+        return raw_cmd, args, None
+        
+    return None, s, None

genetinav/command_router.py

@@ -0,0 +1,33 @@
+"""Command routing and registry for GenetiNav."""
+from typing import Callable, Dict, Tuple
+
+# Registry entry: (handler, description, keybinding_shortcut)
+CommandRegistry = Dict[str, Tuple[Callable[[], None], str, str]]
+
+
+class CommandRouter:
+    """Dispatches commands to their appropriate handlers.
+
+    The *live* argument accepts any object with ``stop()`` and ``start()``
+    methods — used by the Textual app with a ``DummyLive`` stub that is a
+    no-op, since Textual manages its own render loop.
+    """
+
+    def __init__(self, registry: CommandRegistry, live) -> None:
+        self._registry = registry
+        self._live = live
+
+    @property
+    def registry(self) -> CommandRegistry:
+        """Access the command registry."""
+        return self._registry
+
+    def dispatch(self, command: str) -> None:
+        handler_info = self._registry.get(command)
+        if handler_info:
+            handler = handler_info[0]
+            self._live.stop()
+            try:
+                handler()
+            finally:
+                self._live.start()