fix: enforce --offline flag, add datasets CLI check, and log missing GTDB index

The --offline flag was parsed but never enforced during simulation.
Now SpeciesResolver and download_genome respect offline mode by
skipping NCBI network calls and raising clear errors for uncached
genomes. Also adds an early check for the datasets CLI before
attempting downloads, with actionable install instructions.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: druvus

nanopore_simulator/core/simulator.py

@@ -162,7 +162,7 @@ def _resolve_species_inputs(self) -> None:
         ):
             return
 
-        resolver = SpeciesResolver()
+        resolver = SpeciesResolver(offline=self.config.offline_mode)
         resolved_genomes: List[Path] = []
         abundances: List[float] = []
 
@@ -192,7 +192,9 @@ def _resolve_species_inputs(self) -> None:
                 if ref is None:
                     raise ValueError(f"Could not resolve organism: {org.name}")
 
-                genome_path = download_genome(ref, resolver.cache)
+                genome_path = download_genome(
+                    ref, resolver.cache, offline=self.config.offline_mode
+                )
                 resolved_genomes.append(genome_path)
                 abundances.append(org.abundance)
 
@@ -208,7 +210,9 @@ def _resolve_species_inputs(self) -> None:
                         msg += f". Did you mean: {', '.join(suggestions)}?"
                     raise ValueError(msg)
 
-                genome_path = download_genome(ref, resolver.cache)
+                genome_path = download_genome(
+                    ref, resolver.cache, offline=self.config.offline_mode
+                )
                 resolved_genomes.append(genome_path)
 
             # Resolve taxids
@@ -217,7 +221,9 @@ def _resolve_species_inputs(self) -> None:
                 if ref is None:
                     raise ValueError(f"Could not resolve taxid: {taxid}")
 
-                genome_path = download_genome(ref, resolver.cache)
+                genome_path = download_genome(
+                    ref, resolver.cache, offline=self.config.offline_mode
+                )
                 resolved_genomes.append(genome_path)
 
             # Set abundances

nanopore_simulator/core/species.py

@@ -126,6 +126,10 @@ def __init__(self, index_path: Path) -> None:
     def _load_index(self) -> None:
         """Load the TSV index file into memory."""
         if not self.index_path.exists():
+            logger.debug(
+                "GTDB index not found at %s; species resolution will use NCBI.",
+                self.index_path,
+            )
             return
         with open(self.index_path) as f:
             # Skip header line
@@ -314,6 +318,7 @@ def __init__(
         self,
         index_dir: Optional[Path] = None,
         cache_dir: Optional[Path] = None,
+        offline: bool = False,
     ) -> None:
         """Initialize the species resolver.
 
@@ -322,6 +327,8 @@ def __init__(
                 ~/.nanorunner/indexes/ using the HOME environment variable.
             cache_dir: Directory for genome cache. If None, defaults to
                 ~/.nanorunner/genomes/ using the HOME environment variable.
+            offline: If True, skip NCBI network lookups and rely only on the
+                local GTDB index and cached genomes.
         """
         if index_dir is None:
             home = Path(os.environ.get("HOME", Path.home()))
@@ -330,6 +337,7 @@ def __init__(
         self._gtdb = GTDBIndex(index_dir / "gtdb_species.tsv")
         self._ncbi = NCBIResolver()
         self._cache = GenomeCache(cache_dir)
+        self._offline = offline
 
     def resolve(self, species_name: str) -> Optional[GenomeRef]:
         """Resolve a species name to a genome reference.
@@ -349,7 +357,9 @@ def resolve(self, species_name: str) -> Optional[GenomeRef]:
         if ref is not None:
             return ref
 
-        # Fall back to NCBI
+        # Fall back to NCBI (skip in offline mode)
+        if self._offline:
+            return None
         return self._ncbi.resolve_by_name(species_name)
 
     def resolve_taxid(self, taxid: int) -> Optional[GenomeRef]:
@@ -361,6 +371,8 @@ def resolve_taxid(self, taxid: int) -> Optional[GenomeRef]:
         Returns:
             GenomeRef if found, None otherwise.
         """
+        if self._offline:
+            return None
         return self._ncbi.resolve_by_taxid(taxid)
 
     def suggest(self, partial_name: str) -> List[str]:
@@ -384,7 +396,9 @@ def cache(self) -> GenomeCache:
         return self._cache
 
 
-def download_genome(ref: GenomeRef, cache: GenomeCache) -> Path:
+def download_genome(
+    ref: GenomeRef, cache: GenomeCache, offline: bool = False
+) -> Path:
     """Download a genome and cache it.
 
     Uses the NCBI datasets CLI to download the genome sequence for the
@@ -394,19 +408,39 @@ def download_genome(ref: GenomeRef, cache: GenomeCache) -> Path:
     Args:
         ref: Genome reference specifying the accession to download.
         cache: Genome cache instance for storing the downloaded genome.
+        offline: If True, raise an error instead of downloading when the
+            genome is not already cached.
 
     Returns:
         Path to the cached genome file (gzip compressed).
 
     Raises:
-        RuntimeError: If the download fails or no .fna file is found.
+        RuntimeError: If the download fails, no .fna file is found,
+            offline mode is enabled and the genome is not cached, or
+            the datasets CLI is not installed.
     """
     # Check cache first
     cached_path = cache.get_cached_path(ref)
     if cached_path.exists():
         logger.info(f"Using cached genome: {cached_path}")
         return cached_path
 
+    # Offline mode: genome must already be cached
+    if offline:
+        raise RuntimeError(
+            f"Genome {ref.accession} ({ref.name}) is not cached and "
+            "offline mode is enabled. Run 'nanorunner download' first "
+            "to cache the required genomes."
+        )
+
+    # Check that datasets CLI is available before attempting download
+    if shutil.which("datasets") is None:
+        raise RuntimeError(
+            f"Cannot download genome {ref.accession}: "
+            "the 'datasets' CLI (ncbi-datasets-cli) is not installed. "
+            "Install with: conda install -c conda-forge ncbi-datasets-cli"
+        )
+
     # Download via datasets CLI
     logger.info(f"Downloading genome: {ref.accession}")
 

tests/test_simulator_species.py

@@ -325,3 +325,39 @@ def test_no_resolution_for_copy_operation(self, tmp_path):
             sim = NanoporeSimulator(config, enable_monitoring=False)
             # Should not have instantiated resolver
             mock_resolver_cls.assert_not_called()
+
+    def test_offline_mode_passes_flag(self, tmp_path):
+        """Test that offline_mode is forwarded to resolver and download."""
+        config = SimulationConfig(
+            target_dir=tmp_path / "output",
+            operation="generate",
+            species_inputs=["Escherichia coli"],
+            sample_type="pure",
+            read_count=10,
+            reads_per_file=10,
+            offline_mode=True,
+        )
+
+        with patch(
+            "nanopore_simulator.core.simulator.SpeciesResolver"
+        ) as mock_resolver_cls:
+            mock_resolver = MagicMock()
+            mock_resolver_cls.return_value = mock_resolver
+
+            mock_ref = GenomeRef(
+                "Escherichia coli", "GCF_000005845.2", "gtdb", "bacteria"
+            )
+            mock_resolver.resolve.return_value = mock_ref
+
+            genome_path = tmp_path / "genome.fa"
+            genome_path.write_text(">chr1\nATCGATCGATCG\n")
+
+            with patch(
+                "nanopore_simulator.core.simulator.download_genome",
+                return_value=genome_path,
+            ) as mock_download:
+                sim = NanoporeSimulator(config, enable_monitoring=False)
+                mock_resolver_cls.assert_called_once_with(offline=True)
+                mock_download.assert_called_once_with(
+                    mock_ref, mock_resolver.cache, offline=True
+                )

tests/test_species.py

@@ -155,6 +155,12 @@ def test_lookup_case_insensitive(self, tmp_path):
         assert ref is not None
         assert ref.name == "Escherichia coli"
 
+    def test_missing_index_file(self, tmp_path):
+        """Test GTDBIndex with nonexistent file returns None without error."""
+        index = GTDBIndex(tmp_path / "nonexistent.tsv")
+        ref = index.lookup("Escherichia coli")
+        assert ref is None
+
     def test_fuzzy_suggestions(self, tmp_path):
         """Test suggest returns matching species names for partial input"""
         index_file = tmp_path / "gtdb_species.tsv"
@@ -306,6 +312,20 @@ def test_cache_property(self, tmp_path, monkeypatch):
         assert isinstance(resolver.cache, GenomeCache)
         assert resolver.cache.cache_dir == tmp_path / "genomes"
 
+    def test_resolve_offline_skips_ncbi(self, tmp_path, monkeypatch):
+        """Test that offline mode skips NCBI resolution."""
+        # Empty GTDB index so lookup will miss
+        index_file = tmp_path / "indexes" / "gtdb_species.tsv"
+        index_file.parent.mkdir(parents=True, exist_ok=True)
+        index_file.write_text("species\taccession\tdomain\n")
+        monkeypatch.setenv("HOME", str(tmp_path))
+
+        resolver = SpeciesResolver(index_dir=tmp_path / "indexes", offline=True)
+        with patch.object(resolver._ncbi, "resolve_by_name") as mock_ncbi:
+            ref = resolver.resolve("Saccharomyces cerevisiae")
+            assert ref is None
+            mock_ncbi.assert_not_called()
+
     def test_default_index_dir(self, tmp_path, monkeypatch):
         """Test that default index directory is used when not specified"""
         # Create default index location
@@ -433,3 +453,33 @@ def create_empty_zip(*args, **kwargs):
 
             with pytest.raises(RuntimeError, match="No .fna file found"):
                 download_genome(ref, cache)
+
+    def test_download_genome_no_datasets_cli(self, tmp_path):
+        """Test error when datasets CLI is not installed."""
+        cache = GenomeCache(cache_dir=tmp_path)
+        ref = GenomeRef("E. coli", "GCF_000005845.2", "gtdb", "bacteria")
+
+        with patch("nanopore_simulator.core.species.shutil.which", return_value=None):
+            with pytest.raises(RuntimeError, match="ncbi-datasets-cli"):
+                download_genome(ref, cache)
+
+    def test_download_genome_offline_not_cached(self, tmp_path):
+        """Test error when offline mode is enabled and genome is not cached."""
+        cache = GenomeCache(cache_dir=tmp_path)
+        ref = GenomeRef("E. coli", "GCF_000005845.2", "gtdb", "bacteria")
+
+        with pytest.raises(RuntimeError, match="offline mode"):
+            download_genome(ref, cache, offline=True)
+
+    def test_download_genome_offline_cached(self, tmp_path):
+        """Test that offline mode returns cached genome without error."""
+        cache = GenomeCache(cache_dir=tmp_path)
+        ref = GenomeRef("E. coli", "GCF_000005845.2", "gtdb", "bacteria")
+
+        # Pre-create cached file
+        cached_path = cache.get_cached_path(ref)
+        cached_path.parent.mkdir(parents=True, exist_ok=True)
+        cached_path.write_text("cached")
+
+        path = download_genome(ref, cache, offline=True)
+        assert path == cached_path