use anyhow::{Context, Result};
use clap::{Args, ValueEnum};
use serde::Deserialize;
use crate::fmt::{human_count, relative_time_rfc3339};
use crate::hf;
const DOCKER_HUB_SEARCH_URL: &str = "https://hub.docker.com/api/search/v4";
const MAX_LIMIT: u32 = 64;
const MODELPACK_MANIFEST: &str = "application/vnd.cncf.model.manifest.v1+json";
#[derive(Args, Debug)]
pub struct SearchArgs {
#[arg(value_name = "QUERY")]
pub query: String,
#[arg(
long,
short = 'n',
default_value_t = 25,
value_parser = clap::value_parser!(u32).range(1..=MAX_LIMIT as i64)
)]
pub limit: u32,
#[arg(long, value_enum)]
pub registry: Option<Registry>,
}
#[derive(ValueEnum, Clone, Copy, Debug, PartialEq, Eq)]
pub enum Registry {
#[value(alias = "docker.io", alias = "hub")]
Docker,
#[value(alias = "huggingface", alias = "hf.co")]
Hf,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Hit {
pub name: String,
pub pulls: Option<u64>,
pub likes: Option<u64>,
pub updated: Option<String>,
}
pub fn run(args: &SearchArgs) -> Result<()> {
let query = args.query.trim();
anyhow::ensure!(!query.is_empty(), "search query must not be empty");
let hits = tokio::runtime::Runtime::new()
.context("start tokio runtime")?
.block_on(search(query, args.limit, args.registry))?;
if hits.is_empty() {
anyhow::bail!("no models found for {query:?}");
}
print!("{}", render(&hits));
Ok(())
}
async fn search(query: &str, limit: u32, registry: Option<Registry>) -> Result<Vec<Hit>> {
let client = hf::api_client()?;
match registry {
Some(Registry::Docker) => search_docker_hub(&client, query, limit).await,
Some(Registry::Hf) => search_hugging_face(&client, query, limit).await,
None => {
let (docker, hugging_face) = tokio::join!(
search_docker_hub(&client, query, limit),
search_hugging_face(&client, query, limit),
);
match (docker, hugging_face) {
(Ok(mut hits), Ok(more)) => {
hits.extend(more);
Ok(hits)
}
(Ok(hits), Err(e)) => {
eprintln!(
"[llmman] Hugging Face search failed, showing Docker Hub only: {e:#}"
);
Ok(hits)
}
(Err(e), Ok(hits)) => {
eprintln!(
"[llmman] Docker Hub search failed, showing Hugging Face only: {e:#}"
);
Ok(hits)
}
(Err(docker), Err(hugging_face)) => Err(docker
.context(format!("Hugging Face: {hugging_face:#}"))
.context("search failed on both registries")),
}
}
}
}
#[derive(Debug, Deserialize)]
struct HubSearchResponse {
#[serde(default)]
results: Vec<HubResult>,
}
#[derive(Debug, Deserialize)]
struct HubResult {
name: String,
#[serde(default)]
star_count: u64,
#[serde(default)]
raw_pull_count: Option<u64>,
#[serde(default)]
updated_at: Option<String>,
#[serde(default)]
archived: bool,
#[serde(default)]
media_types: Vec<String>,
}
impl HubResult {
fn is_modelpack(&self) -> bool {
self.media_types.iter().any(|t| t == MODELPACK_MANIFEST)
}
}
async fn search_docker_hub(client: &reqwest::Client, query: &str, limit: u32) -> Result<Vec<Hit>> {
let page = |kind| async move {
let url = docker_hub_search_url(query, kind)?;
hf::api::get_json::<HubSearchResponse>(client, url.as_str(), None).await
};
let (typed, untyped) = tokio::join!(page(Some("model")), page(None));
let pages = match (typed, untyped) {
(Ok(a), Ok(b)) => vec![a, b],
(Ok(a), Err(_)) | (Err(_), Ok(a)) => vec![a],
(Err(e), Err(_)) => return Err(e.context("Docker Hub model search")),
};
Ok(docker_hub_hits(pages, limit))
}
fn docker_hub_search_url(query: &str, kind: Option<&'static str>) -> Result<reqwest::Url> {
let size = MAX_LIMIT.to_string();
let mut params = vec![
("query", query),
("from", "0"),
("size", size.as_str()),
("sort", "pull_count"),
("order", "desc"),
];
params.extend(kind.map(|k| ("type", k)));
reqwest::Url::parse_with_params(DOCKER_HUB_SEARCH_URL, params)
.context("build Docker Hub search URL")
}
fn docker_hub_hits(pages: Vec<HubSearchResponse>, limit: u32) -> Vec<Hit> {
let mut seen = std::collections::HashSet::new();
let mut rows: Vec<HubResult> = pages
.into_iter()
.flat_map(|r| r.results)
.filter(|r| !r.archived && r.is_modelpack())
.filter(|r| seen.insert(r.name.clone()))
.collect();
rows.sort_by_key(|r| std::cmp::Reverse(r.raw_pull_count.unwrap_or(0)));
rows.into_iter()
.take(limit as usize)
.map(|r| {
let name = if r.name.contains('/') {
format!("docker.io/{}", r.name)
} else {
format!("docker.io/library/{}", r.name)
};
Hit {
name,
pulls: r.raw_pull_count,
likes: Some(r.star_count),
updated: r.updated_at,
}
})
.collect()
}
async fn search_hugging_face(
client: &reqwest::Client,
query: &str,
limit: u32,
) -> Result<Vec<Hit>> {
let endpoint = hf::hf_endpoint("hf.co");
let token = hf::token();
let models = hf::api::search_models(client, &endpoint, query, limit, token.as_deref()).await?;
Ok(models.into_iter().map(hugging_face_hit).collect())
}
fn hugging_face_hit(model: hf::api::SearchHit) -> Hit {
Hit {
name: format!("hf.co/{}", model.id),
pulls: Some(model.downloads),
likes: Some(model.likes),
updated: model.last_modified,
}
}
fn render(hits: &[Hit]) -> String {
let dash = || "-".to_string();
let rows: Vec<[String; 4]> = hits
.iter()
.map(|h| {
[
h.name.clone(),
h.pulls.map(human_count).unwrap_or_else(dash),
h.likes.map(|n| n.to_string()).unwrap_or_else(dash),
h.updated
.as_deref()
.map(relative_time_rfc3339)
.unwrap_or_else(dash),
]
})
.collect();
let headers = ["NAME", "PULLS", "LIKES", "UPDATED"];
let widths: Vec<usize> = (0..headers.len())
.map(|c| {
rows.iter()
.map(|r| r[c].len())
.max()
.unwrap_or(0)
.max(headers[c].len())
})
.collect();
let line = |cells: [&str; 4]| {
format!(
"{:<w0$} {:<w1$} {:<w2$} {}\n",
cells[0],
cells[1],
cells[2],
cells[3],
w0 = widths[0],
w1 = widths[1],
w2 = widths[2],
)
};
let mut out = line(headers);
for r in &rows {
out.push_str(&line([&r[0], &r[1], &r[2], &r[3]]));
}
out
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn docker_hub_search_url_sorts_by_pulls() {
for (kind, suffix) in [(Some("model"), "&type=model"), (None, "")] {
let url = docker_hub_search_url("qwen", kind).unwrap();
assert_eq!(
url.as_str(),
format!(
"{DOCKER_HUB_SEARCH_URL}?query=qwen&from=0&size=64\
&sort=pull_count&order=desc{suffix}"
)
);
}
}
#[test]
fn docker_hub_rows_become_pullable_references() {
let typed = r#"{"total": 4, "results": [
{"name": "ai/qwen3", "short_description": "Qwen3 LLM", "star_count": 210,
"pull_count": "500K+", "raw_pull_count": 614283,
"updated_at": "2026-08-17T14:03:18.618971Z", "archived": false,
"media_types": ["application/vnd.cncf.model.manifest.v1+json",
"application/vnd.docker.ai.model.config.v0.1+json"],
"content_types": ["model"]},
{"name": "ai/qwen2.5", "star_count": 13, "raw_pull_count": 163532,
"media_types": ["application/vnd.docker.ai.model.config.v0.1+json"],
"content_types": ["model"]},
{"name": "ai/qwen3-embedding", "star_count": 1, "raw_pull_count": 74850,
"media_types": ["application/vnd.cncf.model.manifest.v1+json",
"application/vnd.docker.ai.model.config.v0.1+json"],
"content_types": ["model"]},
{"name": "ai/old", "archived": true, "star_count": 0,
"media_types": ["application/vnd.cncf.model.manifest.v1+json",
"application/vnd.docker.ai.model.config.v0.1+json"],
"content_types": ["model"]}
]}"#;
let untyped = r#"{"total": 6, "results": [
{"name": "ai/qwen3", "star_count": 210, "raw_pull_count": 614283,
"media_types": ["application/vnd.cncf.model.manifest.v1+json",
"application/vnd.docker.ai.model.config.v0.1+json"],
"content_types": ["model"]},
{"name": "library/nginx", "star_count": 99999, "raw_pull_count": 9999999,
"media_types": ["application/vnd.docker.distribution.manifest.v2+json"],
"content_types": ["image"]},
{"name": "ai/qwen3.8", "star_count": 4, "raw_pull_count": 98764,
"media_types": ["application/vnd.cncf.model.manifest.v1+json"],
"content_types": ["unrecognized"]},
{"name": "someone/qwen3.8-27b", "star_count": 0, "raw_pull_count": 90000,
"media_types": ["application/vnd.huggingface.model.v1"],
"content_types": ["unrecognized"]},
{"name": "official-thing", "star_count": 1,
"media_types": ["application/vnd.cncf.model.manifest.v1+json"]},
{"name": "ai/third", "star_count": 0,
"media_types": ["application/vnd.cncf.model.manifest.v1+json"]}
]}"#;
let typed: HubSearchResponse = serde_json::from_str(typed).unwrap();
let untyped: HubSearchResponse = serde_json::from_str(untyped).unwrap();
let hits = docker_hub_hits(vec![typed, untyped], 4);
let names: Vec<&str> = hits.iter().map(|h| h.name.as_str()).collect();
assert_eq!(
names,
[
"docker.io/ai/qwen3",
"docker.io/ai/qwen3.8",
"docker.io/ai/qwen3-embedding",
"docker.io/library/official-thing"
]
);
assert_eq!(
hits[0],
Hit {
name: "docker.io/ai/qwen3".into(),
pulls: Some(614283),
likes: Some(210),
updated: Some("2026-08-17T14:03:18.618971Z".into()),
}
);
assert_eq!(hits[3].pulls, None);
assert_eq!(hits[3].updated, None);
}
#[test]
fn hugging_face_rows_become_pullable_references() {
let body = r#"[
{"id": "unsloth/Qwen3-8B-GGUF", "likes": 989, "downloads": 12853002,
"lastModified": "2025-07-31T10:27:38.000Z"},
{"id": "someone/bare"}
]"#;
let models: Vec<hf::api::SearchHit> = serde_json::from_str(body).unwrap();
let hits: Vec<Hit> = models.into_iter().map(hugging_face_hit).collect();
assert_eq!(
hits[0],
Hit {
name: "hf.co/unsloth/Qwen3-8B-GGUF".into(),
pulls: Some(12853002),
likes: Some(989),
updated: Some("2025-07-31T10:27:38.000Z".into()),
}
);
assert_eq!(hits[1].pulls, Some(0));
assert_eq!(hits[1].updated, None);
}
#[test]
fn render_aligns_columns_and_dashes_missing_values() {
let hits = vec![
Hit {
name: "docker.io/ai/qwen3".into(),
pulls: Some(614_283),
likes: Some(210),
updated: None,
},
Hit {
name: "hf.co/unsloth/Qwen3-8B-GGUF".into(),
pulls: Some(12_853_002),
likes: Some(989),
updated: None,
},
];
let out = render(&hits);
assert_eq!(
out,
"NAME PULLS LIKES UPDATED\n\
docker.io/ai/qwen3 614.3K 210 -\n\
hf.co/unsloth/Qwen3-8B-GGUF 12.9M 989 -\n"
);
}
}