hf2ollama-python-cli-tool 1.0.0__py3-none-any.whl

hf2ollama/hf/api.py

@@ -0,0 +1,197 @@
+"""HuggingFace API client - search repos and list GGUF files."""
+
+from __future__ import annotations
+
+import logging
+from contextlib import contextmanager
+from dataclasses import dataclass
+from typing import Iterator
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+HF_API_BASE = "https://huggingface.co/api"
+
+
+@dataclass
+class RepoInfo:
+    """Metadata for a HuggingFace model repository."""
+
+    repo_id: str
+    downloads: int
+    likes: int
+    last_modified: str
+
+
+@dataclass
+class GGUFFile:
+    """A GGUF file in a HuggingFace repository."""
+
+    filename: str
+    size_bytes: int
+    repo_id: str
+
+    @property
+    def size_gb(self) -> float:
+        """Return file size in gigabytes."""
+        return self.size_bytes / (1024**3)
+
+    @property
+    def size_display(self) -> str:
+        """Return human-readable size string."""
+        if self.size_bytes >= 1024**3:
+            return f"{self.size_gb:.1f} GB"
+        return f"{self.size_bytes / (1024**2):.0f} MB"
+
+
+@contextmanager
+def _get_client(client: httpx.Client | None) -> Iterator[httpx.Client]:
+    """Yield an httpx client, creating one if not provided."""
+    if client is not None:
+        yield client
+    else:
+        owned = httpx.Client(timeout=15.0)
+        try:
+            yield owned
+        finally:
+            owned.close()
+
+
+def search_gguf_repos(
+    query: str,
+    limit: int = 20,
+    sort: str = "downloads",
+    client: httpx.Client | None = None,
+) -> list[RepoInfo]:
+    """Search HuggingFace for GGUF model repos.
+
+    Parameters
+    ----------
+    query : str
+        Search query string.
+    limit : int
+        Maximum number of results.
+    sort : str
+        Sort field (downloads, likes, lastModified).
+    client : httpx.Client | None
+        Optional shared HTTP client.
+
+    Returns
+    -------
+    list[RepoInfo]
+        Matching repositories sorted by the given field.
+
+    """
+    with _get_client(client) as c:
+        params = {
+            "search": query,
+            "filter": "gguf",
+            "sort": sort,
+            "direction": "-1",
+            "limit": str(limit),
+        }
+        resp = c.get(f"{HF_API_BASE}/models", params=params)
+        resp.raise_for_status()
+
+        results: list[RepoInfo] = []
+        for item in resp.json():
+            results.append(
+                RepoInfo(
+                    repo_id=item.get("id", ""),
+                    downloads=item.get("downloads", 0),
+                    likes=item.get("likes", 0),
+                    last_modified=item.get("lastModified", ""),
+                )
+            )
+        logger.debug("Search '%s' returned %d results", query, len(results))
+        return results
+
+
+def list_gguf_files(
+    repo_id: str,
+    client: httpx.Client | None = None,
+) -> list[GGUFFile]:
+    """List GGUF files in a HuggingFace repo with their sizes.
+
+    Parameters
+    ----------
+    repo_id : str
+        HuggingFace repo (e.g., bartowski/Qwen2.5-Coder-7B-Instruct-GGUF).
+    client : httpx.Client | None
+        Optional shared HTTP client.
+
+    Returns
+    -------
+    list[GGUFFile]
+        GGUF files sorted by size ascending.
+
+    """
+    with _get_client(client) as c:
+        resp = c.get(f"{HF_API_BASE}/models/{repo_id}/tree/main")
+        resp.raise_for_status()
+
+        files: list[GGUFFile] = []
+        for item in resp.json():
+            path: str = item.get("path", "")
+            if path.lower().endswith(".gguf"):
+                files.append(
+                    GGUFFile(
+                        filename=path,
+                        size_bytes=item.get("size", 0),
+                        repo_id=repo_id,
+                    )
+                )
+        logger.debug("Repo '%s' has %d GGUF files", repo_id, len(files))
+        return sorted(files, key=lambda f: f.size_bytes)
+
+
+def find_gguf_by_quant(
+    repo_id: str,
+    quant: str = "Q4_K_M",
+    client: httpx.Client | None = None,
+) -> GGUFFile | None:
+    """Find a specific quantization in a repo.
+
+    Parameters
+    ----------
+    repo_id : str
+        HuggingFace repo ID.
+    quant : str
+        Quantization level to match in the filename.
+    client : httpx.Client | None
+        Optional shared HTTP client.
+
+    Returns
+    -------
+    GGUFFile | None
+        Matching file, or None if not found.
+
+    """
+    files = list_gguf_files(repo_id, client=client)
+    quant_lower = quant.lower()
+
+    for f in files:
+        if quant_lower in f.filename.lower():
+            return f
+
+    return None
+
+
+def get_download_url(repo_id: str, filename: str) -> str:
+    """Build the direct download URL for a file.
+
+    Parameters
+    ----------
+    repo_id : str
+        HuggingFace repo ID.
+    filename : str
+        Name of the file to download.
+
+    Returns
+    -------
+    str
+        Direct download URL.
+
+    """
+    return f"https://huggingface.co/{repo_id}/resolve/main/{filename}"

hf2ollama/hf/download.py

@@ -0,0 +1,121 @@
+"""Standard download with httpx - resumable, with progress bar."""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+import httpx
+from rich.progress import (
+    BarColumn,
+    DownloadColumn,
+    Progress,
+    TextColumn,
+    TimeRemainingColumn,
+    TransferSpeedColumn,
+)
+
+from hf2ollama.hf.api import _get_client
+
+logger = logging.getLogger(__name__)
+
+_DOWNLOAD_TIMEOUT = httpx.Timeout(connect=15.0, read=300.0, write=30.0, pool=10.0)
+
+
+def download_file(
+    url: str,
+    dest_path: str,
+    client: httpx.Client | None = None,
+    chunk_size: int = 4 * 1024 * 1024,
+) -> Path:
+    """Download a file with resume support and progress bar.
+
+    Parameters
+    ----------
+    url : str
+        Direct download URL.
+    dest_path : str
+        Local path to write the file.
+    client : httpx.Client | None
+        Optional shared HTTP client. Creates one if not provided.
+    chunk_size : int
+        Download chunk size in bytes (default 4MB).
+
+    Returns
+    -------
+    Path
+        Path to the downloaded file.
+
+    """
+    dest = Path(dest_path)
+    dest.parent.mkdir(parents=True, exist_ok=True)
+
+    with _get_client(client) as c:
+        existing_size: int = dest.stat().st_size if dest.exists() else 0
+
+        headers: dict[str, str] = {}
+        if existing_size > 0:
+            headers["Range"] = f"bytes={existing_size}-"
+            logger.info("Resuming download from byte %d", existing_size)
+
+        with c.stream("GET", url, headers=headers, follow_redirects=True) as resp:
+            if resp.status_code == 416:
+                logger.info("File already fully downloaded: %s", dest)
+                return dest
+
+            resp.raise_for_status()
+
+            total_size: int | None = None
+            if resp.status_code == 206:
+                content_range = resp.headers.get("content-range", "")
+                if "/" in content_range:
+                    total_size = int(content_range.split("/")[-1])
+                mode = "ab"
+            else:
+                cl = resp.headers.get("content-length")
+                total_size = int(cl) if cl else None
+                existing_size = 0
+                mode = "wb"
+
+            progress = Progress(
+                TextColumn("[bold blue]{task.description}"),
+                BarColumn(),
+                DownloadColumn(),
+                TransferSpeedColumn(),
+                TimeRemainingColumn(),
+            )
+
+            filename = Path(url.split("/")[-1].split("?")[0]).name
+            with progress:
+                task = progress.add_task(
+                    filename[:40],
+                    total=total_size,
+                    completed=existing_size,
+                )
+
+                with open(dest, mode) as f:
+                    for chunk in resp.iter_bytes(chunk_size=chunk_size):
+                        f.write(chunk)
+                        progress.advance(task, len(chunk))
+
+        return dest
+
+
+def validate_file_size(path: str, expected_size: int) -> bool:
+    """Check if downloaded file matches expected size.
+
+    Parameters
+    ----------
+    path : str
+        Path to the downloaded file.
+    expected_size : int
+        Expected file size in bytes.
+
+    Returns
+    -------
+    bool
+        True if file size matches.
+
+    """
+    actual = Path(path).stat().st_size
+    return actual == expected_size

hf2ollama/modelfile/__init__.py

@@ -0,0 +1 @@
+"""Modelfile generation - chat templates and model family detection."""

hf2ollama/modelfile/generator.py

@@ -0,0 +1,90 @@
+"""Model family detection and Modelfile generation."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from hf2ollama.modelfile.templates import TEMPLATES
+
+
+def detect_family(filename: str) -> str:
+    """Detect model family from GGUF filename."""
+    lower = filename.lower()
+
+    if re.search(r"deepseek|ds[-_]?r1", lower):
+        return "deepseek"
+    if re.search(r"llama[-_]?4", lower):
+        return "llama4"
+    if re.search(r"llama[-_]?3", lower):
+        return "llama3"
+    if re.search(r"gemma[-_]?[234]?", lower) and "gemma" in lower:
+        return "gemma"
+    if re.search(r"qwen|qwq", lower):
+        return "qwen"
+    if re.search(r"mistral|mixtral|nemo", lower):
+        return "mistral"
+    if re.search(r"phi[-_]?[34]?", lower) and "phi" in lower:
+        return "phi"
+    if "granite" in lower:
+        return "granite"
+    if re.search(r"command[-_]?r|c4ai", lower):
+        return "command-r"
+    if re.search(r"starcoder|codellama", lower):
+        return "qwen"
+
+    return "chatml"
+
+
+def sanitize_model_name(filename: str) -> str:
+    """Generate an Ollama model name from a GGUF filename."""
+    base = re.sub(r"\.gguf$", "", filename, flags=re.IGNORECASE)
+
+    quant_match = re.search(r"[-_](Q\d[^.-]*)", base, re.IGNORECASE)
+    tag = ""
+    if quant_match:
+        tag = quant_match.group(1).lower()
+        base = base[: quant_match.start()]
+
+    name = re.sub(r"[^a-z0-9._-]", "-", base.lower())
+    name = re.sub(r"-+", "-", name).strip("-")
+
+    if tag:
+        name = f"{name}:{tag}"
+
+    return name
+
+
+def generate_modelfile(
+    gguf_path: str,
+    family: str | None = None,
+    temperature: float = 0.7,
+    top_p: float = 0.9,
+) -> str:
+    """Generate an Ollama Modelfile for a GGUF file."""
+    filename = Path(gguf_path).name
+
+    if family is None:
+        family = detect_family(filename)
+
+    tmpl = TEMPLATES.get(family, TEMPLATES["chatml"])
+
+    lines = [
+        f"FROM ./{filename}",
+        "",
+        f'TEMPLATE """{tmpl.template}"""',
+        "",
+    ]
+
+    for stop in tmpl.stop_tokens:
+        lines.append(f'PARAMETER stop "{stop}"')
+
+    lines.extend(
+        [
+            "",
+            f"PARAMETER temperature {temperature}",
+            f"PARAMETER top_p {top_p}",
+        ]
+    )
+
+    return "\n".join(lines)

hf2ollama/modelfile/templates.py

@@ -0,0 +1,134 @@
+"""Chat templates and stop tokens for each model family.
+
+Ported from ConvertToOllama.ps1. These are Go template strings that Ollama
+interprets at runtime. The {{ .System }}, {{ .Prompt }}, {{ .Response }}
+placeholders are Ollama's template variables.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ChatTemplate:
+    """Go template string and stop tokens for an Ollama Modelfile."""
+
+    template: str
+    stop_tokens: list[str]
+
+
+TEMPLATES: dict[str, ChatTemplate] = {
+    "llama4": ChatTemplate(
+        template=(
+            "{{- if .System }}<|header_start|>system<|header_end|>\n\n"
+            "{{ .System }}<|eot|>{{- end }}\n"
+            "<|header_start|>user<|header_end|>\n\n"
+            "{{ .Prompt }}<|eot|>\n"
+            "<|header_start|>assistant<|header_end|>\n\n"
+            "{{ .Response }}<|eot|>"
+        ),
+        stop_tokens=["<|eot|>", "<|end_of_text|>"],
+    ),
+    "llama3": ChatTemplate(
+        template=(
+            "{{- if .System }}<|start_header_id|>system<|end_header_id|>\n\n"
+            "{{ .System }}<|eot_id|>{{- end }}\n"
+            "<|start_header_id|>user<|end_header_id|>\n\n"
+            "{{ .Prompt }}<|eot_id|>\n"
+            "<|start_header_id|>assistant<|end_header_id|>\n\n"
+            "{{ .Response }}<|eot_id|>"
+        ),
+        stop_tokens=["<|eot_id|>", "<|end_of_text|>"],
+    ),
+    "gemma": ChatTemplate(
+        template=(
+            "{{- if .System }}<start_of_turn>user\n"
+            "{{ .System }}\n\n"
+            "{{ .Prompt }}<end_of_turn>\n"
+            "<start_of_turn>model\n"
+            "{{ .Response }}<end_of_turn>{{- else }}\n"
+            "<start_of_turn>user\n"
+            "{{ .Prompt }}<end_of_turn>\n"
+            "<start_of_turn>model\n"
+            "{{ .Response }}<end_of_turn>{{- end }}"
+        ),
+        stop_tokens=["<end_of_turn>"],
+    ),
+    "qwen": ChatTemplate(
+        template=(
+            "{{- if .System }}<|im_start|>system\n"
+            "{{ .System }}<|im_end|>\n"
+            "{{- end }}\n"
+            "<|im_start|>user\n"
+            "{{ .Prompt }}<|im_end|>\n"
+            "<|im_start|>assistant\n"
+            "{{ .Response }}<|im_end|>"
+        ),
+        stop_tokens=["<|im_end|>", "<|endoftext|>"],
+    ),
+    "mistral": ChatTemplate(
+        template=(
+            "{{- if .System }}[INST] {{ .System }}\n\n"
+            "{{ .Prompt }} [/INST]{{ .Response }}"
+            "{{- else }}[INST] {{ .Prompt }} [/INST]{{ .Response }}{{- end }}"
+        ),
+        stop_tokens=["[INST]", "</s>"],
+    ),
+    "phi": ChatTemplate(
+        template=(
+            "{{- if .System }}<|system|>\n"
+            "{{ .System }}<|end|>\n"
+            "{{- end }}\n"
+            "<|user|>\n"
+            "{{ .Prompt }}<|end|>\n"
+            "<|assistant|>\n"
+            "{{ .Response }}<|end|>"
+        ),
+        stop_tokens=["<|end|>", "<|endoftext|>"],
+    ),
+    "deepseek": ChatTemplate(
+        template=(
+            "{{- if .System }}<|begin▁of▁sentence|>"
+            "{{ .System }}\n{{- end }}\n"
+            "<|User|>{{ .Prompt }}\n"
+            "<|Assistant|>{{ .Response }}<|end▁of▁sentence|>"
+        ),
+        stop_tokens=["<|end▁of▁sentence|>"],
+    ),
+    "granite": ChatTemplate(
+        template=(
+            "{{- if .System }}<|start_of_role|>system<|end_of_role|>\n"
+            "{{ .System }}<|end_of_text|>\n"
+            "{{- end }}\n"
+            "<|start_of_role|>user<|end_of_role|>\n"
+            "{{ .Prompt }}<|end_of_text|>\n"
+            "<|start_of_role|>assistant<|end_of_role|>\n"
+            "{{ .Response }}<|end_of_text|>"
+        ),
+        stop_tokens=["<|end_of_text|>"],
+    ),
+    "command-r": ChatTemplate(
+        template=(
+            "{{- if .System }}<|START_OF_TURN_TOKEN|><|SYSTEM_TOKEN|>"
+            "{{ .System }}<|END_OF_TURN_TOKEN|>{{- end }}\n"
+            "<|START_OF_TURN_TOKEN|><|USER_TOKEN|>{{ .Prompt }}<|END_OF_TURN_TOKEN|>\n"
+            "<|START_OF_TURN_TOKEN|><|CHATBOT_TOKEN|>{{ .Response }}<|END_OF_TURN_TOKEN|>"
+        ),
+        stop_tokens=["<|END_OF_TURN_TOKEN|>"],
+    ),
+    "chatml": ChatTemplate(
+        template=(
+            "{{- if .System }}<|im_start|>system\n"
+            "{{ .System }}<|im_end|>\n"
+            "{{- end }}\n"
+            "<|im_start|>user\n"
+            "{{ .Prompt }}<|im_end|>\n"
+            "<|im_start|>assistant\n"
+            "{{ .Response }}<|im_end|>"
+        ),
+        stop_tokens=["<|im_end|>"],
+    ),
+}
+
+SUPPORTED_FAMILIES = list(TEMPLATES.keys())

hf2ollama/network/__init__.py

@@ -0,0 +1 @@
+"""Network modules - environment detection and SSL certificate patching."""

hf2ollama/network/detect.py

@@ -0,0 +1,58 @@
+"""Network environment detection - SSL and HuggingFace reachability checks."""
+
+from __future__ import annotations
+
+import logging
+import os
+import ssl
+from dataclasses import dataclass
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class NetworkStatus:
+    """Result of a network diagnostic check."""
+
+    hf_reachable: bool = False
+    hf_ssl_ok: bool = False
+    hf_error: str = ""
+    proxy_configured: bool = False
+    proxy_url: str = ""
+    system_certs_available: bool = False
+    cert_count: int = 0
+
+
+def check_network() -> NetworkStatus:
+    """Check HuggingFace reachability and SSL certificate status."""
+    status = NetworkStatus()
+
+    status.proxy_url = os.environ.get("HTTPS_PROXY", os.environ.get("https_proxy", ""))
+    status.proxy_configured = bool(status.proxy_url)
+
+    try:
+        ctx = ssl.create_default_context()
+        certs = ctx.get_ca_certs(binary_form=True)
+        status.cert_count = len(certs)
+        status.system_certs_available = status.cert_count > 50
+    except (ssl.SSLError, OSError) as e:
+        logger.debug("Failed to read system certs: %s", e)
+
+    try:
+        httpx.get("https://huggingface.co/api/models?limit=1", timeout=10.0)
+        status.hf_reachable = True
+        status.hf_ssl_ok = True
+    except httpx.ConnectError as e:
+        err = str(e).lower()
+        if "ssl" in err or "certificate" in err:
+            status.hf_reachable = False
+            status.hf_ssl_ok = False
+            status.hf_error = "SSL certificate verification failed"
+        else:
+            status.hf_error = str(e)[:100]
+    except (httpx.TimeoutException, httpx.HTTPStatusError, OSError) as e:
+        status.hf_error = str(e)[:100]
+
+    return status

hf2ollama/network/ssl_fix.py

@@ -0,0 +1,76 @@
+"""SSL certificate configuration - use OS trust store instead of certifi defaults."""
+
+from __future__ import annotations
+
+import logging
+import os
+import ssl
+import tempfile
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+_PATCHED = False
+
+
+def apply_ssl_fix(
+    ca_bundle: str | None = None,
+    proxy: str | None = None,
+) -> str:
+    """Configure Python to use the OS certificate store for SSL verification.
+
+    Exports system CA certificates and sets environment variables so that
+    httpx, requests, and urllib3 use the OS trust store.
+
+    Returns the path to the CA bundle being used.
+    """
+    global _PATCHED
+    if _PATCHED:
+        return os.environ.get("SSL_CERT_FILE", "")
+
+    bundle = ca_bundle or _export_system_certs()
+    os.environ["SSL_CERT_FILE"] = bundle
+    os.environ["REQUESTS_CA_BUNDLE"] = bundle
+    os.environ["CURL_CA_BUNDLE"] = bundle
+
+    if proxy:
+        os.environ["HTTPS_PROXY"] = proxy
+        os.environ["HTTP_PROXY"] = proxy
+
+    _PATCHED = True
+    return bundle
+
+
+def _export_system_certs() -> str:
+    """Export system certificates to a PEM file."""
+    certs: set[str] = set()
+
+    ctx = ssl.create_default_context()
+    for cert_der in ctx.get_ca_certs(binary_form=True):
+        pem = ssl.DER_cert_to_PEM_cert(cert_der)
+        certs.add(pem)
+
+    try:
+        import certifi
+
+        with open(certifi.where(), "r", encoding="utf-8") as f:
+            content = f.read()
+        in_cert = False
+        current: list[str] = []
+        for line in content.splitlines(True):
+            if "BEGIN CERTIFICATE" in line:
+                in_cert = True
+                current = [line]
+            elif "END CERTIFICATE" in line:
+                current.append(line)
+                certs.add("".join(current))
+                in_cert = False
+            elif in_cert:
+                current.append(line)
+    except ImportError:
+        pass
+
+    cert_dir = Path(tempfile.gettempdir()) / "hf2ollama"
+    cert_dir.mkdir(exist_ok=True)
+    bundle = cert_dir / "ca_bundle.pem"
+    bundle.write_text("\n".join(sorted(certs)), encoding="utf-8")
+    return str(bundle)