feat!: add GCS model provider

- Add first-class GCS support across common, client, and server layers,
  including proto/provider enums, DB mapping, cache stats/listing/clear, and
  provider-aware request routing.
- Introduce `modelexpress_common::providers::gcs` with strict
  `gs://bucket/path` canonicalization, safe cache layout validation,
  ancestor/descendant overlap protection, and resumable downloads with CRC32C
  verification.
- Store GCS cache metadata in `.mx/manifest.json` and use that manifest for
  cache discovery, listing, and download planning instead of marker-file
  metadata.
- Canonicalize model names at request boundaries and keep the server as the
  source of truth for `Client::request_model`, with direct download used only
  when the initial client connection cannot be established.
- Update dependency wiring for Google Cloud Storage support and align tests
  with the final provider-aware client and cache behavior.

BREAKING CHANGE:

- `Client::request_model` now requires an explicit `provider` argument.
- Removed public APIs: `preload_model_to_cache`,
  `request_model_with_provider_and_fallback`, `request_model_server_only`, and
  `download_model_directly`.
- Renamed `request_model_with_provider` to `request_model_on_server`.

Signed-off-by: Andrew Paprotsky <apaprotskyi@nvidia.com>

Author: andrewpaprotsky

Cargo.lock

@@ -28,7 +28,9 @@ axum = "0.8"
 chrono = { version = "0.4", features = ["serde"] }
 clap = { version = "4.5", features = ["derive", "env"] }
 config = { version = "0.15", features = ["yaml", "toml", "json"] }
+crc32c = "0.6.8"
 colored = "3.0.0"
+google-cloud-storage = { version = "1.9.0", default-features = false }
 hf-hub = { version = "0.4.3", default-features = false, features = [
     "tokio",
     "rustls-tls",
@@ -39,6 +41,7 @@ modelexpress-client = { path = "modelexpress_client", version = "0.3.0" }
 modelexpress-server = { path = "modelexpress_server", version = "0.3.0" }
 once_cell = "1.21.3"
 prost = "0.13"
+rustls = { version = "0.23.37", default-features = false, features = ["ring", "std"] }
 rusqlite = { version = "0.37", features = ["bundled", "chrono"] }
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"

Cargo.toml

@@ -115,7 +115,7 @@ async fn main() {
 #[allow(clippy::expect_used)]
 mod tests {
     use super::modules::args::{Cli, Commands};
-    use clap::Parser;
+    use clap::{Parser, ValueEnum};
     use modelexpress_client::ModelProvider;
 
     #[test]
@@ -139,6 +139,16 @@ mod tests {
         assert_eq!(provider, ModelProvider::HuggingFace);
     }
 
+    #[test]
+    fn test_cli_model_provider_value_enum() {
+        let parsed = ModelProvider::from_str("hugging-face", false)
+            .expect("Failed to parse hugging-face provider");
+        assert_eq!(parsed, ModelProvider::HuggingFace);
+
+        let parsed = ModelProvider::from_str("gcs", false).expect("Failed to parse gcs provider");
+        assert_eq!(parsed, ModelProvider::Gcs);
+    }
+
     #[test]
     fn test_cli_flattened_client_args_parsing() {
         // Test that the flattened ClientArgs fields are accessible through Cli
@@ -200,20 +210,40 @@ mod tests {
     }
 
     #[test]
-    fn test_cli_model_clear_defaults_to_hugging_face_provider() {
+    fn test_cli_model_clear_parses_explicit_provider() {
         let parsed = Cli::try_parse_from([
             "modelexpress-cli",
             "model",
             "clear",
             "--provider",
-            "hugging-face",
-            "dev/bake/qwen/rev123",
-        ]);
-        assert!(parsed.is_ok());
+            "gcs",
+            "gs://bucket/dev/bake/qwen/rev123",
+        ])
+        .expect("Expected clear command to parse with explicit provider");
 
-        let missing_provider =
-            Cli::try_parse_from(["modelexpress-cli", "model", "clear", "dev/bake/qwen/rev123"])
-                .expect("Expected clear command to parse without provider");
+        let Commands::Model { command } = parsed.command else {
+            panic!("Expected model command");
+        };
+        let super::modules::args::ModelCommands::Clear {
+            provider,
+            model_name,
+        } = command
+        else {
+            panic!("Expected clear subcommand");
+        };
+        assert_eq!(provider, ModelProvider::Gcs);
+        assert_eq!(model_name, "gs://bucket/dev/bake/qwen/rev123");
+    }
+
+    #[test]
+    fn test_cli_model_clear_defaults_to_hugging_face_provider() {
+        let missing_provider = Cli::try_parse_from([
+            "modelexpress-cli",
+            "model",
+            "clear",
+            "gs://bucket/dev/bake/qwen/rev123",
+        ])
+        .expect("Expected clear command to parse without provider");
 
         let Commands::Model { command } = missing_provider.command else {
             panic!("Expected model command");
@@ -226,6 +256,6 @@ mod tests {
             panic!("Expected clear subcommand");
         };
         assert_eq!(provider, ModelProvider::HuggingFace);
-        assert_eq!(model_name, "dev/bake/qwen/rev123");
+        assert_eq!(model_name, "gs://bucket/dev/bake/qwen/rev123");
     }
 }

modelexpress_client/src/bin/cli.rs

@@ -4,39 +4,21 @@
 #![allow(clippy::expect_used)]
 
 use modelexpress_client::{Client, ClientConfig, ModelProvider};
-use tracing::{error, info};
+use tracing::info;
 
 #[tokio::main]
 async fn main() -> Result<(), Box<dyn std::error::Error>> {
-    // Initialize logging
     tracing_subscriber::fmt::init();
 
-    info!("Testing model download with server fallback...");
+    info!("Testing smart fallback with unavailable server...");
 
-    let model_name = "google-t5/t5-small";
-
-    // Test smart fallback - this should work whether server is running or not
-    info!("Attempting to download model with smart fallback...");
-
-    match Client::request_model_with_smart_fallback(
-        model_name,
+    Client::request_model_with_smart_fallback(
+        "google-t5/t5-small",
         ModelProvider::HuggingFace,
-        ClientConfig::default(),
+        ClientConfig::for_testing("http://127.0.0.1:54321"),
         false,
     )
-    .await
-    {
-        Ok(()) => {
-            info!("✅ SUCCESS: Model '{model_name}' downloaded successfully!");
-            info!(
-                "The download worked either via server (if running) or direct download (if server unavailable)"
-            );
-        }
-        Err(e) => {
-            error!("❌ FAILED: Could not download model '{model_name}': {e}");
-            return Err(e.into());
-        }
-    }
+    .await?;
 
     Ok(())
 }

modelexpress_client/src/bin/fallback_test.rs

@@ -6,7 +6,10 @@ use super::output::{print_human_readable, print_output};
 use super::payload::read_payload;
 use colored::*;
 use modelexpress_client::{Client, ClientConfig, ModelProvider};
-use modelexpress_common::cache::{CacheConfig, CacheStats, ModelInfo};
+use modelexpress_common::{
+    cache::{CacheConfig, CacheStats, ModelInfo},
+    download,
+};
 use serde_json::Value;
 use std::io::Write;
 use std::path::PathBuf;
@@ -174,20 +177,13 @@ async fn download_model(
     let result = match strategy {
         DownloadStrategy::SmartFallback => {
             debug!("Using smart fallback strategy");
+            let mut config = config.clone();
             if let Some(cache_config) = cache_config {
-                let mut client = Client::new_with_cache(config.clone(), cache_config).await?;
-                client
-                    .preload_model_to_cache(&model_name, provider, false)
-                    .await
-            } else {
-                Client::request_model_with_smart_fallback(
-                    model_name.clone(),
-                    provider,
-                    config,
-                    false,
-                )
-                .await
+                config.cache = cache_config;
             }
+            Client::request_model_with_smart_fallback(model_name.clone(), provider, config, false)
+                .await
+                .map(|_| ())
         }
         DownloadStrategy::ServerOnly => {
             debug!("Using server-only strategy");
@@ -197,12 +193,23 @@ async fn download_model(
                 Client::new(config.clone()).await?
             };
             client
-                .request_model_with_provider(&model_name, provider, false)
+                .request_model(&model_name, provider, false)
                 .await
+                .map(|_| ())
         }
         DownloadStrategy::Direct => {
             debug!("Using direct download strategy");
-            Client::download_model_directly(model_name.clone(), provider, false).await
+            download::download_model(
+                &model_name,
+                provider,
+                cache_config.map(|config| config.local_path),
+                false,
+            )
+            .await
+            .map(|_| ())
+            .map_err(|e| {
+                modelexpress_common::Error::Server(format!("Direct download failed: {e}")).into()
+            })
         }
     };
 
@@ -246,7 +253,7 @@ async fn download_model(
                     print_output(&output, format);
                 }
             }
-            return Err(Box::new(e));
+            return Err(e);
         }
     }
 

modelexpress_client/src/bin/modules/handlers.rs

@@ -9,6 +9,7 @@
 #![allow(clippy::expect_used)]
 
 use modelexpress_client::{Client, ClientConfig};
+use modelexpress_common::download;
 use modelexpress_common::models::ModelProvider;
 use std::env;
 use std::time::{Duration, Instant};
@@ -100,7 +101,7 @@ async fn run_concurrent_model_test(model_name: &str) -> Result<(), Box<dyn std::
         info!("Client 1: Requesting model {model_name1}");
         let start = Instant::now();
         client1
-            .request_model(model_name1, false)
+            .request_model(model_name1, ModelProvider::default(), false)
             .await
             .expect("Client 1 failed to download model");
         info!("Client 1: Model downloaded in {:?}", start.elapsed());
@@ -116,7 +117,7 @@ async fn run_concurrent_model_test(model_name: &str) -> Result<(), Box<dyn std::
         info!("Client 2: Requesting model {model_name2}");
         let start = Instant::now();
         client2
-            .request_model(model_name2, false)
+            .request_model(model_name2, ModelProvider::default(), false)
             .await
             .expect("Client 2 failed to download model");
         info!("Client 2: Model downloaded in {:?}", start.elapsed());
@@ -140,7 +141,10 @@ async fn run_single_model_test(model_name: &str) -> Result<(), Box<dyn std::erro
     info!("Client: Requesting model {model_name}");
     let start = Instant::now();
 
-    match client.request_model(model_name.to_string(), false).await {
+    match client
+        .request_model(model_name.to_string(), ModelProvider::default(), false)
+        .await
+    {
         Ok(()) => {
             info!("Client: Model downloaded in {:?}", start.elapsed());
             info!("Client completed in {:?}", start_time.elapsed());
@@ -154,7 +158,7 @@ async fn run_single_model_test(model_name: &str) -> Result<(), Box<dyn std::erro
     }
 }
 
-/// Test fallback functionality including server fallback, direct download, and smart fallback
+/// Test download functionality including server fallback, direct download, and smart fallback
 async fn run_fallback_test(model_name: &str) -> Result<(), Box<dyn std::error::Error>> {
     info!("Testing fallback functionality (assuming server is running)...");
     let mut client = Client::new(ClientConfig::default()).await?;
@@ -163,7 +167,7 @@ async fn run_fallback_test(model_name: &str) -> Result<(), Box<dyn std::error::E
 
     // This should work via server since it's running
     match client
-        .request_model_with_provider_and_fallback(model_name, ModelProvider::HuggingFace, false)
+        .request_model(model_name, ModelProvider::HuggingFace, false)
         .await
     {
         Ok(()) => {
@@ -181,21 +185,27 @@ async fn run_fallback_test(model_name: &str) -> Result<(), Box<dyn std::error::E
     info!("Testing direct download (bypassing server)...");
     let start_direct = Instant::now();
 
-    match Client::download_model_directly(model_name, ModelProvider::HuggingFace, false).await {
-        Ok(()) => {
+    match download::download_model(
+        model_name,
+        ModelProvider::HuggingFace,
+        Some(ClientConfig::default().cache.local_path.clone()),
+        false,
+    )
+    .await
+    {
+        Ok(_) => {
             info!("Model downloaded directly in {:?}", start_direct.elapsed());
         }
         Err(e) => {
             return Err(format!("Failed to download model directly: {e}").into());
         }
     }
 
-    // Test smart fallback (will use server if available, direct download if not)
     info!("Testing smart fallback...");
     let start_smart = Instant::now();
 
     match Client::request_model_with_smart_fallback(
-        model_name,
+        model_name.to_string(),
         ModelProvider::HuggingFace,
         ClientConfig::default(),
         false,
@@ -207,11 +217,12 @@ async fn run_fallback_test(model_name: &str) -> Result<(), Box<dyn std::error::E
                 "Model downloaded with smart fallback in {:?}",
                 start_smart.elapsed()
             );
-            info!(
-                "FALLBACK TEST PASSED: Server-with-fallback, direct download, and smart fallback all work"
-            );
-            Ok(())
         }
-        Err(e) => Err(format!("Failed to download model with smart fallback: {e}").into()),
+        Err(e) => {
+            return Err(format!("Failed to download model with smart fallback: {e}").into());
+        }
     }
+
+    info!("FALLBACK TEST PASSED: Server, direct download, and smart fallback paths all work");
+    Ok(())
 }