Native compilation and Homebrew instructions. (#18)

* chore: Added `nuitka` as a candidate native code compiler system.

* chore: Bumped patch version.

* chore: Simple improvement with list-models displaying a sorted list.

* chore: Added sorting in all listing and tags. HF model sorting is per page only.
chore: Upgraded dependencies.

* chore: Code refactoring.
chore: Case-insensitive sorting of models and tags.
chore: Minor version bumped.

* feat: Added Nuitka-based native compilation script.
chore: Updated README.
chore: Upgraded packages.

* chore: Added a `version` command.

* chore: Updated README to reflect the `version` command.

* chore: Updated README to reflect Homebrew-based installation.
chore: Upgraded dependencies.

Author: anirbanbasu

.gitignore

@@ -210,3 +210,6 @@ __marimo__/
 conf/
 # Pytest profiling
 prof/
+
+# Native binaries created by Nuitka
+od-native*

README.md

@@ -115,27 +115,44 @@ Usage: od [OPTIONS] COMMAND [ARGS]...
 
  A command-line interface for the Ollama downloader.
 
-╭─ Options ───────────────────────────────────────────────────────────────────────────────────╮
-│ --help          Show this message and exit.                                                 │
-╰─────────────────────────────────────────────────────────────────────────────────────────────╯
-╭─ Commands ──────────────────────────────────────────────────────────────────────────────────╮
-│ show-config         Shows the application configuration as JSON.                            │
-│ auto-config         Displays an automatically inferred configuration.                       │
-│ list-models         Lists all available models in the Ollama library. If pagination options │
-│                     are not provided, all models will be listed.                            │
-│ list-tags           Lists all tags for a specific model.                                    │
-│ model-download      Downloads a specific Ollama model with the given tag.                   │
-│ hf-list-models      Lists available models from Hugging Face that can be downloaded into    │
-│                     Ollama.                                                                 │
-│ hf-list-tags        Lists all available quantisations as tags for a Hugging Face model that │
-│                     can be downloaded into Ollama. Note that these are NOT the same as      │
-│                     Hugging Face model tags.                                                │
-│ hf-model-download   Downloads a specified Hugging Face model.                               │
-╰─────────────────────────────────────────────────────────────────────────────────────────────╯
+╭─ Options ────────────────────────────────────────────────────────────────────────────────╮
+│ --help          Show this message and exit.                                              │
+╰──────────────────────────────────────────────────────────────────────────────────────────╯
+╭─ Commands ───────────────────────────────────────────────────────────────────────────────╮
+│ version             Shows the app version of Ollama downloader.                          │
+│ show-config         Shows the application configuration as JSON.                         │
+│ auto-config         Displays an automatically inferred configuration.                    │
+│ list-models         Lists all available models in the Ollama library. If pagination      │
+│                     options are not provided, all models will be listed.                 │
+│ list-tags           Lists all tags for a specific model.                                 │
+│ model-download      Downloads a specific Ollama model with the given tag.                │
+│ hf-list-models      Lists available models from Hugging Face that can be downloaded into │
+│                     Ollama.                                                              │
+│ hf-list-tags        Lists all available quantisations as tags for a Hugging Face model   │
+│                     that can be downloaded into Ollama. Note that these are NOT the same │
+│                     as Hugging Face model tags.                                          │
+│ hf-model-download   Downloads a specified Hugging Face model.                            │
+╰──────────────────────────────────────────────────────────────────────────────────────────╯
 ```
 
 You can also use `--help` on each command to see command-specific help.
 
+### `version`
+
+The `version` command displays the application version.
+
+Running `uv run od version --help` displays the following.
+
+```bash
+Usage: od version [OPTIONS]
+
+ Shows the app version of Ollama downloader.
+
+╭─ Options ────────────────────────────────────────────────────────────────────────────────╮
+│ --help          Show this message and exit.                                              │
+╰──────────────────────────────────────────────────────────────────────────────────────────╯
+```
+
 ### `show-config`
 
 The `show-config` command simply displays the current configuration from the settings file in the configurations directory, if it exists. If it does not exist, it creates that file with the default settings and shows the content of that file.
@@ -372,11 +389,27 @@ tests/test_typer.py                                              62      0   100
 TOTAL                                                           655     95    85%
 ```
 
-There is a handy script for running tests `run-tests.sh` in _WD_. It can accept any parameters to be passed to `pytest`. Thus, tests can be filtered using the `-k` to specify tests to run or not. Likewise, profiling can be done by calling `./run-tests.sh --profile`. The resulting profile information will be generated and saved in _WD_`/prof`. A SVG of the complete profile can be generated by calling `./run-tests.sh --profile --profile-svg`.
+There is a handy script for running tests `run_tests.sh` in _WD_. It can accept any parameters to be passed to `pytest`. Thus, tests can be filtered using the `-k` to specify tests to run or not. Likewise, profiling can be done by calling `./run_tests.sh --profile`. The resulting profile information will be generated and saved in _WD_`/prof`. A SVG of the complete profile can be generated by calling `./run_tests.sh --profile --profile-svg`.
 
 Profile information can also be filtered and a SVG of the filtered profile generated by editing the somewhat hacky script _WD_`/tests/filter_profile_data.py`.
 The script can be run using `uv` as `uv run tests/filter_profile_data.py`.
 
+## Native compilation and execution
+
+This is an _experimental feature_ by which Ollama downloader can be compiled into a single executable binary file -- `od-native` -- using [Nuitka](https://nuitka.net/). To compile the native binary on your platform, run the script `./compile_native.sh`. Notice that you must have the `dev` group dependencies of the project installed.
+
+_Note that having a `.env` file may cause the natively compiled binary to crash, with an error message `OSError: Starting path not found`._ Should you want to pass any of the environment variables to the executable, do so using the command line interface.
+
+Once the native executable has been created, run it from the command line interface as `./od-native` on UNIX/Linux systems and simply `od-native` on Windows. The native executable may have executable file type extension (`.exe`) on Windows.
+
+_Note that the natively compiled binary is unlikely to be significantly faster than the Python code that you can execute using `uv`_. After all, the bottleneck in most of the operations in Ollama downloader is more likely to be the network speed as opposed to code execution speed.
+
+## Installation on macOS and Linux using Homebrew
+
+Ollama downloader can be installed on macOS and Linux using Homebrew so that the installation of Python and the management of a virtual environment is all done by Homebrew leaving a single command `ollama-downloader` available on the command line interface.
+
+To do so, add the new tap by running: `brew tap anirbanbasu/tap`. Then, Ollama downloader can be installed using `brew install ollama-downloader`.
+
 ## Contributing
 
 Install [`pre-commit`](https://pre-commit.com/) for Git by using the `--all-groups` flag for `uv sync`.

compile_native.sh

@@ -0,0 +1,20 @@
+#!/bin/bash
+NATIVE_FILE="od-native"
+PRODUCT_NAME="ollama-downloader"
+# Remove the existing native file
+rm $NATIVE_FILE
+uv run python -m nuitka \
+		--onefile \
+		--standalone \
+		--clean-cache="all" \
+		--disable-cache="all" \
+		--remove-output \
+		--static-libpython="yes" \
+		--noinclude-pytest-mode="nofollow" \
+		--product-name=$PRODUCT_NAME \
+		# Extract version from pyproject.toml but only the numerical parts, e.g., "1.2.3.rc1" -> "1.2.3"
+		--product-version=$(sed -n 's/^version = "\([0-9.]*\).*/\1/p' pyproject.toml | head -n 1) \
+		--output-file=$NATIVE_FILE \
+		--macos-prohibit-multiple-instances \
+		--macos-app-name=$PRODUCT_NAME \
+		src/ollama_downloader/cli.py

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ollama-downloader"
-version = "0.1.1.post1"
+version = "0.2.0"
 description = "A library and Hugging Face model downloader for Ollama."
 readme = "README.md"
 license = "MIT"
@@ -61,6 +61,7 @@ build-backend = "hatchling.build"
 [dependency-groups]
 dev = [
     "icecream>=2.1.7",
+    "nuitka>=2.7.16",
     "pre-commit>=4.3.0",
 ]
 test = [

run-tests.sh renamed to run_tests.sh

@@ -1,18 +1,35 @@
 import logging
-from environs import env
+import os
+from environs import Env
+from marshmallow.validate import OneOf
 from rich.logging import RichHandler
 
-from ollama_downloader.common import EnvVar
-
 try:
     from icecream import ic
 
     ic.configureOutput(includeContext=True)
 except ImportError:  # Graceful fallback if IceCream isn't installed.
     ic = lambda *a: None if not a else (a[0] if len(a) == 1 else a)  # noqa
 
+env = Env()
+if os.path.exists(".env"):  # This check is only necessary for Nuitka-compiled binaries.
+    env.read_env()  # Read .env file, if it exists
+
+
+class EnvVar:
+    LOG_LEVEL = env.str(
+        "LOG_LEVEL",
+        default="info",
+        validate=OneOf(["NOTSET", "DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]),
+    ).upper()
+
+    OD_UA_NAME_VER = env.str("OD_UA_NAME_VER", default="ollama-downloader/0.1.1")
+
+    OD_SETTINGS_FILE = env.str("OD_SETTINGS_FILE", default="conf/settings.json")
+
+
 logging.basicConfig(
-    level=env.str(EnvVar.LOG_LEVEL, default=EnvVar.DEFAULT__LOG_LEVEL).upper(),
+    level=EnvVar.LOG_LEVEL,
     format="%(message)s",
     datefmt="[%X]",
     handlers=[

run-upgrade.sh renamed to run_upgrade.sh

@@ -14,8 +14,9 @@
 from rich import print as print
 from rich import print_json
 import psutil
+from importlib.metadata import version as metadata_version
 
-from ollama_downloader.common import OllamaSystemInfo
+from ollama_downloader.sysinfo import OllamaSystemInfo
 from ollama_downloader.data.data_models import AppSettings
 from ollama_downloader.downloader.ollama_model_downloader import OllamaModelDownloader
 from ollama_downloader.downloader.hf_model_downloader import HuggingFaceModelDownloader
@@ -64,6 +65,24 @@ def _cleanup(self):
 
         logger.debug("Cleanup completed.")
 
+    async def _version(self):
+        package_name = "ollama-downloader"
+        name_splits = package_name.split("-")
+        if len(name_splits) != 2:
+            abbreviation = package_name
+        else:
+            abbreviation = f"{name_splits[0]}{name_splits[1][0]}"
+        return (
+            f"{package_name} ({abbreviation}) version {metadata_version(package_name)}"
+        )
+
+    async def run_version(self):
+        try:
+            result = await self._version()
+            print(result)
+        except Exception as e:
+            logger.error(f"Error in getting version. {e}")
+
     async def _show_config(self):
         return self._model_downloader.settings.model_dump_json()
 
@@ -308,25 +327,11 @@ async def run_list_models(
     ):
         try:
             self._initialize()
-            result = await self._list_models()
-            filtered_result = result
-            if page_size and page:
-                # Adjust page number for 0-based index
-                start_index = (page - 1) * page_size
-                end_index = start_index + page_size
-                filtered_result = result[start_index:end_index]
-            if len(filtered_result) == 0:
-                logger.warning(
-                    f"No models found for the specified page {page} and page size {page_size}. Showing all models instead."
-                )
-                filtered_result = result
-                page = None
-            if page:
-                print(
-                    f"Model identifiers: ({len(filtered_result)}, page {page}): {filtered_result}"
-                )
+            result = await self._list_models(page=page, page_size=page_size)
+            if page and page_size and page_size >= len(result):
+                print(f"Model identifiers: ({len(result)}, page {page}): {result}")
             else:
-                print(f"Model identifiers: ({len(filtered_result)}): {filtered_result}")
+                print(f"Model identifiers: ({len(result)}): {result}")
         except Exception as e:
             logger.error(f"Error in listing models. {e}")
         finally:
@@ -407,6 +412,13 @@ async def run_hf_model_download(self, user_repo_quant: str):
             self._cleanup()
 
 
+@app.command()
+def version():
+    """Shows the app version of Ollama downloader."""
+    app_handler = OllamaDownloaderCLIApp()
+    asyncio.run(app_handler.run_version())
+
+
 @app.command()
 def show_config():
     """Shows the application configuration as JSON."""

src/ollama_downloader/__init__.py

@@ -4,9 +4,8 @@
 from pydantic import AfterValidator, BaseModel, Field, HttpUrl
 from typing import Annotated, ClassVar, List, Optional, Tuple
 
-from environs import env
 
-from ollama_downloader.common import EnvVar
+from ollama_downloader import EnvVar
 
 logger = logging.getLogger(__name__)
 
@@ -96,7 +95,7 @@ def __new__(cls: type["AppSettings"]) -> "AppSettings":
 
     @staticmethod
     def load_or_create_default(
-        settings_file: str = EnvVar.DEFAULT__OD_SETTINGS_FILE,
+        settings_file: str = EnvVar.OD_SETTINGS_FILE,
     ) -> "AppSettings | None":
         """
         Load settings from the configuration file, or create default settings if the file does not exist.
@@ -115,9 +114,7 @@ def load_or_create_default(
 
     @staticmethod
     def load_settings(
-        settings_file: str = env.str(
-            EnvVar.OD_SETTINGS_FILE, default=EnvVar.DEFAULT__OD_SETTINGS_FILE
-        ),
+        settings_file: str = EnvVar.OD_SETTINGS_FILE,
     ) -> "AppSettings | None":
         """
         Load settings from the configuration file.
@@ -140,9 +137,7 @@ def load_settings(
     @staticmethod
     def save_settings(
         settings: "AppSettings",
-        settings_file: str = env.str(
-            EnvVar.OD_SETTINGS_FILE, default=EnvVar.DEFAULT__OD_SETTINGS_FILE
-        ),
+        settings_file: str = EnvVar.OD_SETTINGS_FILE,
     ) -> bool:
         """
         Save the application settings to the configuration file.

src/ollama_downloader/cli.py

@@ -4,10 +4,8 @@
 from urllib.parse import urlparse
 
 
-from environs import env
 from pydantic import Field
 
-from ollama_downloader.common import EnvVar
 from ollama_downloader.data.data_models import ImageManifest
 from ollama_downloader.downloader.model_downloader import ModelDownloader, ModelSource
 
@@ -18,7 +16,6 @@
 
 # Initialize the logger
 logger = logging.getLogger(__name__)
-logger.setLevel(env.str(EnvVar.LOG_LEVEL, default=EnvVar.DEFAULT__LOG_LEVEL).upper())
 
 
 class HuggingFaceModelDownloader(ModelDownloader):
@@ -164,7 +161,10 @@ def list_available_models(
             model_identifiers = [
                 model["modelId"] for model in list(models_response.json())
             ]
-
+        logger.warning(
+            "HuggingFace models are sorted in the context of the selected page only."
+        )
+        model_identifiers.sort(key=lambda s: s.lower())
         return model_identifiers
 
     def list_model_tags(self, model_identifier: str) -> List[str]:
@@ -189,4 +189,5 @@ def list_model_tags(self, model_identifier: str) -> List[str]:
             raise RuntimeError(
                 f"The model {model_identifier} has no support for Ollama."
             )
+        tags.sort(key=lambda s: s.lower())
         return tags