Simply Patrick Hopes can always go up, tears can only come down.

#[derive(Debug, Subcommand)]
enum Command {
    /// 掃描本地資料夾裡的 GGUF 檔案
    Scan { dir: PathBuf },
    /// 搜尋 Hugging Face 上的 GGUF 模型
    HfSearch { query: String, limit: usize },
    /// 從 Hugging Face 下載 GGUF 模型
    HfDownload { name: String, filename: Option<String>, ... },
    /// 用 llama.cpp 跑本地模型推理
    Run { model: String, prompt: String, ... },
}

impl Command {
    fn run(self) -> Result<()> {
        match self {
            Self::Scan { dir } => scan_models(dir),
            Self::HfSearch { query, limit } => search_hugging_face(query, limit),
            Self::HfDownload { .. } => download_hugging_face_model(..),
            Self::Run { .. } => run_model(..),
        }
    }
}

fn resolve_model_path(model: &str, dir: PathBuf) -> Result<PathBuf> {
    let direct_path = PathBuf::from(model);
    if direct_path.try_exists()? {
        return Ok(direct_path);
    }
    let registry = ModelRegistry::scan_dir(&dir)?;
    Ok(registry.find(model)?.path.clone())
}

# 直接給路徑
llm-local-studio run models/Q4_K_M.gguf -p "Hello"

# 或者只給檔名的一部分
llm-local-studio run tinyllama -p "Hello"

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ModelRecord {
    pub id: String,
    pub path: PathBuf,
    pub size_bytes: u64,
    pub source: ModelSource,
    pub status: ModelLoadStatus,
}

fn scan_dir_recursive(dir: &Path, models: &mut Vec<ModelRecord>) -> Result<()> {
    if !dir.try_exists()? {
        return Ok(());
    }
    for entry in fs::read_dir(dir)? {
        let entry = entry?;
        let path = entry.path();
        let metadata = entry.metadata()?;
        if metadata.is_dir() {
            scan_dir_recursive(&path, models)?;
        } else if is_gguf_file(&path) {
            models.push(ModelRecord { ... });
        }
    }
    Ok(())
}

pub fn find(&self, query: &str) -> Result<&ModelRecord> {
    // 第一層：精確比對（不分大小寫）
    let mut matches = self.models.iter().filter(|model| {
        model.id.eq_ignore_ascii_case(query)
            || model.path.file_name()...eq_ignore_ascii_case(query)
    });
    if let Some(model) = matches.next() {
        return Ok(model);
    }

    // 第二層：部分比對（contains）
    let partial_matches = self.models.iter().filter(|model| {
        model.id.to_lowercase().contains(&query_lower)
            || model.path...to_lowercase().contains(&query_lower)
    }).collect::<Vec<_>>();

    match partial_matches.as_slice() {
        [model] => Ok(model),       // 唯一命中
        [] => bail!("no local model matched {query:?}"),
        matches => bail!("model name {query:?} is ambiguous; matches: {ids}"),
    }
}

# 先看下載 URL，不下載
llm-local-studio hf-download TheBloke/TinyLlama-1.1B-GGUF --print-url

# 確認無誤後再下載
llm-local-studio hf-download TheBloke/TinyLlama-1.1B-GGUF

const PREFERRED_QUANTS: &[&str] = &["Q4_K_M", "Q4_K_S", "Q5_K_M", "Q8_0", "Q4_0"];

pub fn choose_gguf_file<'a>(
    &self,
    files: &'a [HuggingFaceFile],
    requested: Option<&str>,
) -> Result<&'a HuggingFaceFile> {
    if let Some(requested) = requested {
        return files.iter()
            .find(|file| file.rfilename == requested)
            .with_context(|| ...);
    }
    for preferred in PREFERRED_QUANTS {
        if let Some(file) = files.iter().find(|file| file.rfilename.contains(preferred)) {
            return Ok(file);
        }
    }
    files.first().context("repository does not contain GGUF files")
}

let temp_path = plan.destination.with_extension("gguf.part");
let mut output = fs::File::create(&temp_path)?;
let bytes_written = io::copy(&mut response, &mut output)?;
drop(output); // 確保 flush

fs::rename(&temp_path, &plan.destination)?;

fn local_model_path(models_dir: &Path, model: &HuggingFaceModelRef, filename: &str) -> Result<PathBuf> {
    if filename.is_empty() || filename.contains("..") {
        anyhow::bail!("invalid Hugging Face filename {filename:?}");
    }
    for component in filename.split('/') {
        if component.is_empty() || component == "." || component == ".." {
            anyhow::bail!("invalid Hugging Face filename {filename:?}");
        }
        path.push(component);
    }
    Ok(path)
}

models/
  huggingface/
    TheBloke/
      TinyLlama-1.1B-GGUF/
        tinyllama-1.1b-chat-v1.0.Q4_K_M.gguf

pub trait InferenceEngine {
    fn load_model(&mut self, request: LoadModelRequest) -> Result<ModelHandle>;
    fn unload_model(&mut self, model_id: &str) -> Result<()>;
    fn health(&self) -> EngineHealth;
}

pub enum EngineHealth {
    NotConfigured,
    Ready,
    Loaded { model_id: String },
    Error { message: String },
}

impl LlamaCppRunner {
    pub fn run(&self, request: &RunModelRequest) -> Result<RunModelOutput> {
        suppress_llama_logs();

        // 1. 初始化 llama.cpp 後端
        let backend = LlamaBackend::init()
            .context("failed to initialize llama.cpp backend")?;

        // 2. 載入 GGUF 模型
        let model = LlamaModel::load_from_file(
            &backend, &request.model_path, &LlamaModelParams::default()
        )?;

        // 3. 建立 context（設定 context window 大小）
        let context_size = NonZeroU32::new(request.context_size)?;
        let context_params = LlamaContextParams::default()
            .with_n_ctx(Some(context_size));
        let mut context = model.new_context(&backend, context_params)?;

        // 4. Tokenize prompt
        let prompt_tokens = model.str_to_token(&request.prompt, AddBos::Always)?;

        // 5. 檢查 context 容量
        let requested_tokens = prompt_tokens.len() + request.max_tokens as usize;
        if requested_tokens > context.n_ctx() as usize {
            anyhow::bail!("prompt plus generated tokens require {requested_tokens} ...");
        }

        // 6. 處理 prompt（一次性送入 KV cache）
        let mut batch = LlamaBatch::new(512, 1);
        for (position, token) in (0_i32..).zip(prompt_tokens.into_iter()) {
            batch.add(token, position, &[0], position == last_prompt_index)?;
        }
        context.decode(&mut batch)?;

        // 7. 逐 token 生成（streaming）
        let mut sampler = LlamaSampler::chain_simple([
            LlamaSampler::dist(1234),
            LlamaSampler::greedy(),
        ]);
        while generated_tokens < request.max_tokens {
            let token = sampler.sample(&context, batch.n_tokens() - 1);
            sampler.accept(token);
            if model.is_eog_token(token) { break; }

            let piece = model.token_to_piece(token, &mut decoder, true, None)?;
            print!("{piece}");        // 逐字印出
            std::io::stdout().flush()?;

            batch.clear();
            batch.add(token, position, &[0], true)?;
            context.decode(&mut batch)?;
            position += 1;
            generated_tokens += 1;
        }

        Ok(RunModelOutput { generated_tokens })
    }
}

if requested_tokens > context.n_ctx() as usize {
    anyhow::bail!("prompt plus generated tokens require {requested_tokens} ...");
}

// 概念上等價於 llama.cpp 內部的 e_model enum
enum ModelArch {
    Llama,
    Mistral,
    Gpt2,
    Phi2,
    Qwen2,
    Gemma,
    Mamba,
    // ... 60+ 種架構
}

# 1. 搜尋 Hugging Face 上的 GGUF 模型
llm-local-studio hf-search "tinyllama gguf"

# 2. 下載模型（自動選 Q4_K_M 量化）
llm-local-studio hf-download TheBloke/TinyLlama-1.1B-GGUF

# 3. 掃描本地已有的模型
llm-local-studio scan models

# 4. 跑推理！
llm-local-studio run tinyllama -p "Tell me a joke about Rust"

llm-local-studio run TheBloke/TinyLlama-1.1B-GGUF \
  -p "Explain ownership in Rust" \
  --ctx-size 2048 \
  -n 256

#[test]
fn parses_hugging_face_model_ref() {
    let model: HuggingFaceModelRef = "TheBloke/TinyLlama-1.1B-GGUF".parse().unwrap();
    assert_eq!(model.owner, "TheBloke");
    assert_eq!(model.repo, "TinyLlama-1.1B-GGUF");
}

#[test]
fn chooses_preferred_quant_when_filename_is_not_requested() {
    let files = vec![
        HuggingFaceFile { rfilename: "model.Q8_0.gguf".into(), size: None },
        HuggingFaceFile { rfilename: "model.Q4_K_M.gguf".into(), size: None },
    ];
    assert_eq!(
        client.choose_gguf_file(&files, None).unwrap().rfilename,
        "model.Q4_K_M.gguf"
    );
}

#[test]
fn builds_local_hugging_face_model_path() {
    let model: HuggingFaceModelRef = "owner/repo".parse().unwrap();
    let path = local_model_path(Path::new("models"), &model, "nested/model.gguf").unwrap();
    // models/huggingface/owner/repo/nested/model.gguf
}