Feat: Added huggingface readme.md format to match l-bom v0.2.0

README.md

@@ -1,21 +1,21 @@
 ---
 title: GUI-BOM
-emoji: 📚
+emoji: 📊
 colorFrom: red
 colorTo: pink
 sdk: static
 pinned: true
 ---
 
-# GUI-BOM
+## GUI-BOM
 
 `GUI-BOM` is a local browser-based wrapper around `L-BOM`, a Python tool that inspects local LLM model artifacts such as `.gguf` and `.safetensors` files and emits a lightweight Software Bill of Materials with file identity, format details, model metadata, and parsing warnings.
 
 The project now supports both a CLI workflow and a polished local GUI for people who would rather click through a browser than work in a command prompt.
 
-## Quick start on Windows
+### Quick start on Windows
 
-### Before you begin
+#### Before you begin
 
 1. Install Python 3.10 or newer for Windows.
 2. During installation, enable the option to add Python to `PATH` if it is offered.
@@ -33,7 +33,7 @@ python --version
 
 `start-gui.bat` needs one of those commands to exist already. It creates a virtual environment and installs the app, but it does not install Python for you.
 
-### Launch with the batch file
+#### Launch with the batch file
 
 1. Download or extract the project to a folder on your PC.
 2. Open the folder in File Explorer.
@@ -44,7 +44,7 @@ python --version
 
 If the script prints `Unable to start the GUI.`, Python is usually missing or not available through `py` or `python`.
 
-### Launch manually from PowerShell
+#### Launch manually from PowerShell
 
 If you prefer to run the setup yourself:
 
@@ -55,7 +55,7 @@ py -3 -m venv .venv
 .venv\Scripts\python -m llm_sbom.cli gui
 ```
 
-## Install
+### Install
 
 ```bash
 pip install .
@@ -67,7 +67,7 @@ For editable local development:
 pip install -e ".[dev]"
 ```
 
-## GUI usage
+### GUI usage
 
 Start the local web app manually after installing the package:
 
@@ -90,7 +90,7 @@ The GUI includes:
 - summary cards, document details, and warning views
 - copy and download actions for JSON, SPDX, and table output
 
-## One-click Windows launch
+### One-click Windows launch
 
 `start-gui.bat` is the fastest way to get started on Windows once Python is installed.
 
@@ -104,7 +104,7 @@ It:
 
 If Python is not installed, the launcher will fail and print `Unable to start the GUI.`
 
-## Docker usage
+### Docker usage
 
 Build the image:
 
@@ -120,7 +120,7 @@ docker run --rm -p 7860:7860 -v C:\models:/models l-bom-gui
 
 Then open `http://127.0.0.1:7860` and browse to `/models` inside the app.
 
-## CLI usage
+### CLI usage
 
 Show the installed version:
 
@@ -140,64 +140,296 @@ Scan a single model file and emit SPDX tag-value:
 l-bom scan .\models\Llama-3.1-8B-Instruct-Q4_K_M.gguf --format spdx
 ```
 
+Scan a single model file and emit a huggingface-style README:
+
+```bash
+l-bom scan .\models\Llama-3.1-8B-Instruct-Q4_K_M.gguf --format hf-readme
+```
+
 Scan a directory recursively and render a table:
 
 ```bash
 l-bom scan .\models --format table
 ```
 
+Export a single model scan as Hugging Face-ready `README.md` content:
+
+```bash
+l-bom scan .\models\Llama-3.1-8B-Instruct-Q4_K_M.gguf --format hf-readme --hf-sdk static --hf-app-file index.html
+```
+
+Override the inferred title and short description for the README front matter:
+
+```bash
+l-bom scan .\models\Llama-3.1-8B-Instruct-Q4_K_M.gguf --format hf-readme --hf-title "Llama 3.1 Demo" --hf-short-description "Quantized GGUF artifact for a local demo space"
+```
+
+
 Skip SHA256 hashing for very large files and write the result to disk:
 
 ```bash
 l-bom scan .\models --no-hash --output .\model-sbom.json
 ```
 
-## Sample JSON output
+### Sample JSON output
+
+Sample JSON output for (`LFM2.5-1.2B-Instruct-Q8_0.gguf`)[https://huggingface.co/LiquidAI/LFM2.5-1.2B-Instruct-GGUF]:
 
 ```json
 {
   "sbom_version": "1.0",
-  "generated_at": "2026-03-24T14:08:22.118000+00:00",
-  "tool_name": "L-BOM",
-  "tool_version": "0.1.0",
-  "model_path": "C:\\models\\Llama-3.1-8B-Instruct-Q4_K_M.gguf",
-  "model_filename": "Llama-3.1-8B-Instruct-Q4_K_M.gguf",
-  "file_size_bytes": 4682873912,
-  "sha256": "8b0b3cb15be2e0a0f4b474230ef326f6180fc76efad1d761bf9ce949f6e785b4",
+  "generated_at": "2026-03-25T04:07:53.262551+00:00",
+  "tool_name": "l-bom",
+  "tool_version": "0.2.0",
+  "model_path": "C:\\models\\LFM2.5-1.2B-Instruct-GGUF\\LFM2.5-1.2B-Instruct-Q8_0.gguf",
+  "model_filename": "LFM2.5-1.2B-Instruct-Q8_0.gguf",
+  "file_size_bytes": 1246253888,
+  "sha256": "f6b981dcb86917fa463f78a362320bd5e2dc45445df147287eedb85e5a30d26a",
   "format": "gguf",
-  "architecture": "llama",
-  "parameter_count": 8030261248,
-  "quantization": "Q4_K_M",
+  "architecture": "lfm2",
+  "parameter_count": 1170340608,
+  "quantization": "Q5_1",
   "dtype": null,
-  "context_length": 8192,
-  "vocab_size": 128256,
-  "license": "llama3.1",
-  "base_model": "meta-llama/Llama-3.1-8B-Instruct",
-  "training_framework": "transformers 4.43.2",
+  "context_length": 128000,
+  "vocab_size": 65536,
+  "license": null,
+  "base_model": null,
+  "training_framework": null,
   "metadata": {
-    "general.name": "Llama 3.1 8B Instruct",
-    "general.file_type": 14,
+    "general.architecture": "lfm2",
+    "general.type": "model",
+    "general.name": "4cd563d5a96af9e7c738b76cd89a0a200db7608f",
+    "general.finetune": "4cd563d5a96af9e7c738b76cd89a0a200db7608f",
+    "general.size_label": "1.2B",
+    "general.license": "other",
+    "general.license.name": "lfm1.0",
+    "general.license.link": "LICENSE",
+    "general.tags": [
+      "liquid",
+      "lfm2.5",
+      "edge",
+      "text-generation"
+    ],
+    "general.languages": [
+      "en",
+      "ar",
+      "zh",
+      "fr",
+      "de",
+      "ja",
+      "ko",
+      "es"
+    ],
+    "lfm2.block_count": 16,
+    "lfm2.context_length": 128000,
+    "lfm2.embedding_length": 2048,
+    "lfm2.feed_forward_length": 8192,
+    "lfm2.attention.head_count": 32,
+    "lfm2.attention.head_count_kv": [
+      0,
+      0,
+      8,
+      0,
+      0,
+      8,
+      0,
+      0,
+      8,
+      0,
+      8,
+      0,
+      8,
+      0,
+      8,
+      0
+    ],
+    "lfm2.rope.freq_base": 1000000.0,
+    "lfm2.attention.layer_norm_rms_epsilon": 9.999999747378752e-06,
+    "lfm2.vocab_size": 65536,
+    "lfm2.shortconv.l_cache": 3,
+    "tokenizer.ggml.model": "gpt2",
+    "tokenizer.ggml.pre": "lfm2",
+    "tokenizer.ggml.tokens": {
+      "type": "array",
+      "element_type": "STRING",
+      "count": 65536,
+      "preview": [
+        "<|pad|>",
+        "<|startoftext|>",
+        "<|endoftext|>",
+        "<|fim_pre|>",
+        "<|fim_mid|>",
+        "<|fim_suf|>",
+        "<|im_start|>",
+        "<|im_end|>",
+        "<|tool_list_start|>",
+        "<|tool_list_end|>",
+        "<|tool_call_start|>",
+        "<|tool_call_end|>",
+        "<|tool_response_start|>",
+        "<|tool_response_end|>",
+        "<|reserved_4|>",
+        "<|reserved_5|>"
+      ],
+      "truncated": true
+    },
+    "tokenizer.ggml.token_type": {
+      "type": "array",
+      "element_type": "INT32",
+      "count": 65536,
+      "preview": [
+        3,
+        3,
+        3,
+        3,
+        3,
+        3,
+        3,
+        3,
+        3,
+        3,
+        3,
+        3,
+        3,
+        3,
+        1,
+        1
+      ],
+      "truncated": true
+    },
+    "tokenizer.ggml.merges": {
+      "type": "array",
+      "element_type": "STRING",
+      "count": 63683,
+      "preview": [
+        "Ċ Ċ",
+        "Ċ ĊĊ",
+        "ĊĊ Ċ",
+        "Ċ ĊĊĊ",
+        "ĊĊ ĊĊ",
+        "ĊĊĊ Ċ",
+        "Ċ ĊĊĊĊ",
+        "ĊĊ ĊĊĊ",
+        "ĊĊĊ ĊĊ",
+        "ĊĊĊĊ Ċ",
+        "Ċ ĊĊĊĊĊ",
+        "ĊĊ ĊĊĊĊ",
+        "ĊĊĊ ĊĊĊ",
+        "ĊĊĊĊ ĊĊ",
+        "ĊĊĊĊĊ Ċ",
+        "Ċ ĊĊĊĊĊĊ"
+      ],
+      "truncated": true
+    },
+    "tokenizer.ggml.bos_token_id": 1,
+    "tokenizer.ggml.eos_token_id": 7,
+    "tokenizer.ggml.padding_token_id": 0,
+    "tokenizer.ggml.add_bos_token": true,
+    "tokenizer.ggml.add_sep_token": false,
+    "tokenizer.ggml.add_eos_token": false,
+    "tokenizer.chat_template": "{{- bos_token -}}\n{%- set keep_past_thinking = keep_past_thinking | default(false) -%}\n{%- set ns = namespace(system_prompt=\"\") -%}\n{%- if messages[0][\"role\"] == \"system\" -%}\n    {%- set ns.system_prompt = messages[0][\"content\"] -%}\n    {%- set messages = messages[1:] -%}\n{%- endif -%}\n{%- if tools -%}\n    {%- set ns.system_prompt = ns.system_prompt + (\"\\n\" if ns.system_prompt else \"\") + \"List of tools: [\" -%}\n    {%- for tool in tools -%}\n        {%- if tool is not string -%}\n            {%- set tool = tool | tojson -%}\n        {%- endif -%}\n        {%- set ns.system_prompt = ns.system_prompt + tool -%}\n        {%- if not loop.last -%}\n            {%- set ns.system_prompt = ns.system_prompt + \", \" -%}\n        {%- endif -%}\n    {%- endfor -%}\n    {%- set ns.system_prompt = ns.system_prompt + \"]\" -%}\n{%- endif -%}\n{%- if ns.system_prompt -%}\n    {{- \"<|im_start|>system\\n\" + ns.system_prompt + \"<|im_end|>\\n\" -}}\n{%- endif -%}\n{%- set ns.last_assistant_index = -1 -%}\n{%- for message in messages -%}\n    {%- if message[\"role\"] == \"assistant\" -%}\n        {%- set ns.last_assistant_index = loop.index0 -%}\n    {%- endif -%}\n{%- endfor -%}\n{%- for message in messages -%}\n    {{- \"<|im_start|>\" + message[\"role\"] + \"\\n\" -}}\n    {%- set content = message[\"content\"] -%}\n    {%- if content is not string -%}\n        {%- set content = content | tojson -%}\n    {%- endif -%}\n    {%- if message[\"role\"] == \"assistant\" and not keep_past_thinking and loop.index0 != ns.last_assistant_index -%}\n        {%- if \"</think>\" in content -%}\n            {%- set content = content.split(\"</think>\")[-1] | trim -%}\n        {%- endif -%}\n    {%- endif -%}\n    {{- content + \"<|im_end|>\\n\" -}}\n{%- endfor -%}\n{%- if add_generation_prompt -%}\n    {{- \"<|im_start|>assistant\\n\" -}}\n{%- endif -%}",
+    "general.quantization_version": 2,
+    "general.file_type": 7,
     "gguf_version": 3,
     "endianness": "little",
     "metadata_keys": [
       "general.architecture",
-      "general.file_type",
-      "llama.context_length",
-      "tokenizer.ggml.tokens"
+      "general.type",
+      "general.name",
+      "general.finetune",
+      "general.size_label",
+      "general.license",
+      "general.license.name",
+      "general.license.link",
+      "general.tags",
+      "general.languages",
+      "lfm2.block_count",
+      "lfm2.context_length",
+      "lfm2.embedding_length",
+      "lfm2.feed_forward_length",
+      "lfm2.attention.head_count",
+      "lfm2.attention.head_count_kv",
+      "lfm2.rope.freq_base",
+      "lfm2.attention.layer_norm_rms_epsilon",
+      "lfm2.vocab_size",
+      "lfm2.shortconv.l_cache",
+      "tokenizer.ggml.model",
+      "tokenizer.ggml.pre",
+      "tokenizer.ggml.tokens",
+      "tokenizer.ggml.token_type",
+      "tokenizer.ggml.merges",
+      "tokenizer.ggml.bos_token_id",
+      "tokenizer.ggml.eos_token_id",
+      "tokenizer.ggml.padding_token_id",
+      "tokenizer.ggml.add_bos_token",
+      "tokenizer.ggml.add_sep_token",
+      "tokenizer.ggml.add_eos_token",
+      "tokenizer.chat_template",
+      "general.quantization_version",
+      "general.file_type"
     ],
-    "sidecar_config": {
-      "model_type": "llama",
-      "architectures": [
-        "LlamaForCausalLM"
-      ],
-      "torch_dtype": "bfloat16",
-      "transformers_version": "4.43.2"
+    "tensor_count": 148,
+    "tensor_type_counts": {
+      "Q8_0": 93,
+      "F32": 55
+    },
+    "tensor_type_parameter_counts": {
+      "Q8_0": 1170210816,
+      "F32": 129792
     }
   },
   "warnings": []
 }
 ```
 
-## License
+## Sample Huggingface Output
+
+Sample hf-readme output for (`LFM2.5-1.2B-Instruct-Q8_0.gguf`)[https://huggingface.co/LiquidAI/LFM2.5-1.2B-Instruct-GGUF]:
+
+```markdown
+---
+title: "LFM2.5-1.2B-Instruct-Q8_0"
+short_description: "GGUF model artifact for LFM2.5-1.2B-Instruct-Q8_0 with 1.17B parameters, 1.2B, Q5_1, 128.00K context"
+tags:
+  - "liquid"
+  - "lfm2.5"
+  - "edge"
+  - "text-generation"
+  - "gguf"
+  - "lfm2"
+  - "q5_1"
+---
+
+# LFM2.5-1.2B-Instruct-Q8_0
+
+GGUF model artifact for LFM2.5-1.2B-Instruct-Q8_0 with 1.17B parameters, 1.2B, Q5_1, 128.00K context
+
+This README content was generated by `L-BOM` from a local model artifact.
+
+## Artifact details
+
+- **Filename:** `LFM2.5-1.2B-Instruct-Q8_0.gguf`
+- **Path:** `C:\models\LFM2.5-1.2B-Instruct-GGUF\LFM2.5-1.2B-Instruct-Q8_0.gguf`
+- **Format:** `gguf`
+- **File size:** `1.16 GiB` (1,246,253,888 bytes)
+- **SHA256:** `f6b981dcb86917fa463f78a362320bd5e2dc45445df147287eedb85e5a30d26a`
+- **Architecture:** `lfm2`
+- **Parameters:** `1,170,340,608` (1.17B)
+- **Size label:** `1.2B`
+- **Quantization:** `Q5_1`
+- **Context length:** `128,000`
+- **Vocabulary size:** `65,536`
+
+## Model metadata
+
+- **License:** `lfm1.0`
+- **License reference:** `LICENSE`
+- **Languages:** `en`, `ar`, `zh`, `fr`, `de`, `ja`, `ko`, `es`
+- **Tags:** `liquid`, `lfm2.5`, `edge`, `text-generation`, `gguf`, `lfm2`, `q5_1`
+Generated with L-BOM. Contribute to L-BOM 💘 development: https://github.com/CHKDSKLabs/l-bom
+```
+
+
+#### License
 
 This project is licensed under the MIT License. See `LICENSE` for the full text.

index.html

@@ -11,7 +11,12 @@
 			<h1>GUI-BOM</h1>
 			<p>GUI-BOM is the graphical user interface for L-BOM, a small Python CLI for inspecting local LLM model artifacts and generating a lightweight software bill of materials.</p>
 			<p>It works with files such as <code>.gguf</code> and <code>.safetensors</code> and reports file identity, format details, model metadata, and parsing warnings.</p>
-			<p>Install it locally with the included .bat file or via Docker, then visit <a href="http://127.0.0.1:7860" target="_blank">http://127.0.0.1:7860</a> to generate output in JSON, SPDX, or table format.</p>
+			<p>Install it locally with the included .bat file or via Docker, then visit <a href="http://127.0.0.1:7860" target="_blank">http://127.0.0.1:7860</a> to generate output in JSON, SPDX, huggingface or table format.</p>
+			<div class="link-grid" aria-label="Project links">
+				<a class="link-chip" href="https://huggingface.co/spaces/CHK-DSK-Labs/gui-bom/tree/main" target="_blank" rel="noreferrer">Files</a>
+				<a class="link-chip" href="https://huggingface.co/spaces/CHK-DSK-Labs/gui-bom/discussions" target="_blank" rel="noreferrer">Community</a>
+				<a class="link-chip" href="https://huggingface.co/CHK-DSK-Labs" target="_blank" rel="noreferrer">CHK-DSK Labs</a>
+			</div>
 			<p>Source, usage examples, and development details are available on <a href="https://github.com/CHKDSKLabs/gui-bom" target="_blank" rel="noreferrer">GitHub</a>.</p>
 		</div>
 	</body>

llm_sbom/__init__.py

@@ -1,4 +1,4 @@
 """Package metadata for L-BOM."""
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 

llm_sbom/cli.py

@@ -10,8 +10,9 @@ from . import __version__
 from .output import render_output
 from .scanner import scan_path
 
+from .huggingface import HuggingFaceReadmeOptions, render_huggingface_readme
 
-@click.group(help="Generate a Software Bill of Materials for local LLM model files.")
+@click.group(help="Generate a Software Bill of Materials for local LLM model files.", epilog="Use --help with any command (for example, l-bom scan --help) for additional information and parameters.")
 def main() -> None:
     pass
 
@@ -20,7 +21,7 @@ def main() -> None:
 @click.option(
     "--format",
     "output_format",
-    type=click.Choice(["json", "spdx", "table"], case_sensitive=False),
+    type=click.Choice(["json", "spdx", "table", "hf-readme"], case_sensitive=False),
     default="json",
     show_default=True,
     help="Choose the output format.",
@@ -35,10 +36,64 @@ def main() -> None:
     is_flag=True,
     help="Skip SHA256 computation for very large model files.",
 )
-def scan(path: Path, output_format: str, output: Path | None, no_hash: bool) -> None:
+@click.option(
+    "--hf-title",
+    type=str,
+    help="Override the inferred title when exporting a Hugging Face README.",
+)
+@click.option(
+    "--hf-sdk",
+    type=click.Choice(["gradio", "docker", "static"], case_sensitive=False),
+    help="Add the Space SDK field to a Hugging Face README export.",
+)
+@click.option(
+    "--hf-app-file",
+    type=str,
+    help="Add the app_file field to a Hugging Face README export.",
+)
+@click.option(
+    "--hf-app-port",
+    type=int,
+    help="Add the app_port field to a Hugging Face README export.",
+)
+@click.option(
+    "--hf-short-description",
+    type=str,
+    help="Override the inferred short_description in a Hugging Face README export.",
+)
+def scan(
+    path: Path,
+    output_format: str,
+    output: Path | None,
+    no_hash: bool,
+    hf_title: str | None,
+    hf_sdk: str | None,
+    hf_app_file: str | None,
+    hf_app_port: int | None,
+    hf_short_description: str | None,
+) -> None:
 
     documents = scan_path(path, compute_hash=not no_hash)
-    rendered = render_output(documents, output_format, color=output is None)
+    if output_format.lower() == "hf-readme":
+        if len(documents) != 1:
+            raise click.ClickException(
+                "Hugging Face README export currently supports scanning a single model file at a time."
+            )
+        if hf_app_port is not None and hf_sdk not in {None, "docker"}:
+            raise click.ClickException("--hf-app-port can only be used with --hf-sdk docker.")
+
+        rendered = render_huggingface_readme(
+            documents[0],
+            HuggingFaceReadmeOptions(
+                title=hf_title,
+                sdk=hf_sdk.lower() if hf_sdk else None,
+                app_file=hf_app_file,
+                app_port=hf_app_port,
+                short_description=hf_short_description,
+            ),
+        )
+    else:
+        rendered = render_output(documents, output_format, color=output is None)
 
     if output is not None:
         write_output_file(output, rendered)
@@ -46,7 +101,7 @@ def scan(path: Path, output_format: str, output: Path | None, no_hash: bool) ->
 
     if rendered.endswith("\n"):
         click.echo(rendered, nl=False, color=True)
-        click.echo("Contribute to L-BOM 💘 development: https://github.com/CHKDSKLabs/l-bom", color=True)
+        click.echo("Generated with L-BOM: SBOM generator for gguf and safetensors files: https://github.com/CHKDSKLabs/l-bom", color=False)
     else:
         click.echo(rendered, color=True)
 

llm_sbom/gui.py

@@ -13,11 +13,12 @@ from typing import Any, TypedDict
 from flask import Flask, jsonify, render_template, request
 
 from . import __version__
+from .huggingface import HuggingFaceReadmeOptions, render_huggingface_readme
 from .output import render_output
 from .scanner import MODEL_SUFFIXES, scan_path
 from .schema import SBOMDocument
 
-OUTPUT_FORMATS = {"json", "spdx", "table"}
+OUTPUT_FORMATS = {"json", "spdx", "table", "hf-readme"}
 
 
 class DirectoryEntry(TypedDict):
@@ -94,7 +95,7 @@ def create_app() -> Flask:
         if not isinstance(raw_path, str) or not raw_path.strip():
             return _error("A model file or directory path is required.", 400)
         if not isinstance(output_format, str) or output_format.lower() not in OUTPUT_FORMATS:
-            return _error("Output format must be one of: json, spdx, table.", 400)
+            return _error("Output format must be one of: json, spdx, table, hf-readme.", 400)
         if not isinstance(compute_hash, bool):
             return _error("The compute_hash value must be true or false.", 400)
 
@@ -109,7 +110,39 @@ def create_app() -> Flask:
 
         documents = scan_path(resolved, compute_hash=compute_hash)
         normalized_format = output_format.lower()
-        rendered_output = render_output(documents, normalized_format, color=False)
+
+        if normalized_format == "hf-readme":
+            if len(documents) != 1:
+                return _error(
+                    "Hugging Face README export currently supports scanning a single model file at a time.",
+                    400,
+                )
+
+            hf_title = payload.get("hf_title") or None
+            hf_sdk = payload.get("hf_sdk") or None
+            hf_app_file = payload.get("hf_app_file") or None
+            hf_app_port = payload.get("hf_app_port") or None
+            hf_short_description = payload.get("hf_short_description") or None
+
+            if hf_sdk and not isinstance(hf_sdk, str):
+                return _error("hf_sdk must be a string.", 400)
+            if hf_sdk and hf_sdk.lower() not in {"gradio", "docker", "static"}:
+                return _error("hf_sdk must be one of: gradio, docker, static.", 400)
+            if hf_app_port is not None and hf_sdk not in {None, "docker"}:
+                return _error("hf_app_port can only be used with hf_sdk docker.", 400)
+
+            rendered_output = render_huggingface_readme(
+                documents[0],
+                HuggingFaceReadmeOptions(
+                    title=hf_title,
+                    sdk=hf_sdk.lower() if hf_sdk else None,
+                    app_file=hf_app_file,
+                    app_port=int(hf_app_port) if hf_app_port is not None else None,
+                    short_description=hf_short_description,
+                ),
+            )
+        else:
+            rendered_output = render_output(documents, normalized_format, color=False)
 
         return jsonify(
             {

llm_sbom/huggingface.py

@@ -0,0 +1,307 @@
+"""Helpers for exporting Hugging Face-friendly README metadata."""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, TypeAlias
+
+from .schema import SBOMDocument
+
+FrontMatterValue: TypeAlias = str | int | bool | list[str]
+FrontMatter: TypeAlias = dict[str, FrontMatterValue]
+
+
+@dataclass(frozen=True)
+class HuggingFaceReadmeOptions:
+    title: str | None = None
+    sdk: str | None = None
+    app_file: str | None = None
+    app_port: int | None = None
+    short_description: str | None = None
+
+
+@dataclass(frozen=True)
+class HuggingFaceReadmeDocument:
+    front_matter: FrontMatter
+    body: str
+
+
+def build_huggingface_readme(
+    document: SBOMDocument, options: HuggingFaceReadmeOptions
+) -> HuggingFaceReadmeDocument:
+
+    title = options.title or _derive_title(document)
+    short_description = options.short_description or _derive_short_description(document, title)
+
+    front_matter: FrontMatter = {
+        "title": title,
+        "short_description": short_description,
+    }
+    if options.sdk:
+        front_matter["sdk"] = options.sdk
+    if options.app_file:
+        front_matter["app_file"] = options.app_file
+    if options.app_port is not None:
+        front_matter["app_port"] = options.app_port
+
+    models = _extract_models(document)
+    if models:
+        front_matter["models"] = models
+
+    tags = _extract_tags(document)
+    if tags:
+        front_matter["tags"] = tags
+
+    body = _render_readme_body(document, title, short_description)
+    return HuggingFaceReadmeDocument(front_matter=front_matter, body=body)
+
+
+def render_huggingface_readme(document: SBOMDocument, options: HuggingFaceReadmeOptions) -> str:
+
+    readme = build_huggingface_readme(document, options)
+    return f"{_render_front_matter(readme.front_matter)}\n\n{readme.body}\n"
+
+
+def _derive_title(document: SBOMDocument) -> str:
+
+    metadata_name = _metadata_string(document.metadata, "general.name")
+    if metadata_name and not _looks_like_hash(metadata_name):
+        return metadata_name
+    return Path(document.model_filename).stem
+
+
+def _derive_short_description(document: SBOMDocument, title: str) -> str:
+
+    details: list[str] = []
+    if document.parameter_count is not None:
+        details.append(f"{_format_compact_number(document.parameter_count)} parameters")
+    size_label = _metadata_string(document.metadata, "general.size_label")
+    if size_label:
+        details.append(size_label)
+    if document.quantization:
+        details.append(document.quantization)
+    if document.context_length is not None:
+        details.append(f"{_format_compact_number(document.context_length)} context")
+
+    summary = f"{document.format.upper()} model artifact for {title}"
+    if details:
+        summary = f"{summary} with {', '.join(details)}"
+    return summary
+
+
+def _extract_models(document: SBOMDocument) -> list[str]:
+
+    candidates = [
+        document.base_model,
+        _metadata_string(document.metadata, "base_model"),
+        _metadata_string(document.metadata, "base_model_repo_id"),
+        _metadata_string(document.metadata, "source_model"),
+    ]
+
+    models: list[str] = []
+    for candidate in candidates:
+        if candidate is None or "/" not in candidate:
+            continue
+        if candidate not in models:
+            models.append(candidate)
+    return models
+
+
+def _extract_tags(document: SBOMDocument) -> list[str]:
+
+    tags: list[str] = []
+    metadata_tags = document.metadata.get("general.tags")
+    if isinstance(metadata_tags, list):
+        for tag in metadata_tags:
+            normalized = _normalize_tag(tag)
+            if normalized and normalized not in tags:
+                tags.append(normalized)
+
+    for value in (document.format, document.architecture, document.quantization):
+        normalized = _normalize_tag(value)
+        if normalized and normalized not in tags:
+            tags.append(normalized)
+
+    return tags
+
+
+def _render_readme_body(document: SBOMDocument, title: str, short_description: str) -> str:
+
+    lines = [
+        f"# {title}",
+        "",
+        short_description,
+        "",
+        "This README content was generated by `L-BOM` from a local model artifact.",
+        "",
+        "## Artifact details",
+        "",
+    ]
+
+    _append_bullet(lines, "Filename", f"`{document.model_filename}`")
+    _append_bullet(lines, "Path", f"`{document.model_path}`")
+    _append_bullet(lines, "Format", _code_or_none(document.format))
+    _append_bullet(lines, "File size", _format_file_size(document.file_size_bytes))
+    _append_bullet(lines, "SHA256", _code_or_none(document.sha256))
+    _append_bullet(lines, "Architecture", _code_or_none(document.architecture))
+    _append_bullet(lines, "Parameters", _format_parameter_count(document.parameter_count))
+    _append_bullet(lines, "Size label", _code_or_none(_metadata_string(document.metadata, "general.size_label")))
+    _append_bullet(lines, "Quantization", _code_or_none(document.quantization))
+    _append_bullet(lines, "Dtype", _code_or_none(document.dtype))
+    _append_bullet(lines, "Context length", _format_optional_int(document.context_length))
+    _append_bullet(lines, "Vocabulary size", _format_optional_int(document.vocab_size))
+
+    metadata_lines: list[str] = []
+    license_name = _extract_license_name(document)
+    license_link = _metadata_string(document.metadata, "general.license.link")
+    _append_bullet(metadata_lines, "License", _code_or_none(license_name))
+    _append_bullet(metadata_lines, "License reference", _code_or_none(license_link))
+    _append_bullet(metadata_lines, "Base model", _code_or_none(document.base_model))
+    _append_bullet(metadata_lines, "Training framework", _code_or_none(document.training_framework))
+
+    languages = _extract_languages(document)
+    if languages:
+        _append_bullet(metadata_lines, "Languages", ", ".join(f"`{language}`" for language in languages))
+
+    tags = _extract_tags(document)
+    if tags:
+        _append_bullet(metadata_lines, "Tags", ", ".join(f"`{tag}`" for tag in tags))
+
+    if metadata_lines:
+        lines.extend(["", "## Model metadata", ""])
+        lines.extend(metadata_lines)
+
+    if document.warnings:
+        lines.extend(["", "## Warnings", ""])
+        for warning in document.warnings:
+            lines.append(f"- {warning}")
+
+    return "\n".join(lines)
+
+
+def _extract_license_name(document: SBOMDocument) -> str | None:
+
+    return (
+        document.license
+        or _metadata_string(document.metadata, "general.license.name")
+        or _metadata_string(document.metadata, "general.license")
+    )
+
+
+def _extract_languages(document: SBOMDocument) -> list[str]:
+
+    raw_languages = document.metadata.get("general.languages")
+    if not isinstance(raw_languages, list):
+        return []
+
+    languages: list[str] = []
+    for language in raw_languages:
+        if not isinstance(language, str):
+            continue
+        normalized = language.strip()
+        if normalized and normalized not in languages:
+            languages.append(normalized)
+    return languages
+
+
+def _append_bullet(lines: list[str], label: str, value: str | None) -> None:
+
+    if value is None:
+        return
+    lines.append(f"- **{label}:** {value}")
+
+
+def _render_front_matter(front_matter: FrontMatter) -> str:
+
+    lines = ["---"]
+    for key, value in front_matter.items():
+        if isinstance(value, list):
+            lines.append(f"{key}:")
+            for item in value:
+                lines.append(f"  - {_yaml_scalar(item)}")
+            continue
+        lines.append(f"{key}: {_yaml_scalar(value)}")
+    lines.append("---")
+    return "\n".join(lines)
+
+
+def _yaml_scalar(value: str | int | bool) -> str:
+
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, int):
+        return str(value)
+    return json.dumps(value, ensure_ascii=False)
+
+
+def _metadata_string(metadata: dict[str, Any], key: str) -> str | None:
+
+    value = metadata.get(key)
+    if not isinstance(value, str):
+        return None
+    stripped = value.strip()
+    return stripped or None
+
+
+def _normalize_tag(value: str | None) -> str | None:
+
+    if value is None:
+        return None
+    normalized = value.strip().lower().replace(" ", "-")
+    return normalized or None
+
+
+def _code_or_none(value: str | None) -> str | None:
+
+    if value is None:
+        return None
+    return f"`{value}`"
+
+
+def _format_optional_int(value: int | None) -> str | None:
+
+    if value is None:
+        return None
+    return f"`{value:,}`"
+
+
+def _format_parameter_count(value: int | None) -> str | None:
+
+    if value is None:
+        return None
+    return f"`{value:,}` ({_format_compact_number(value)})"
+
+
+def _format_compact_number(value: int) -> str:
+
+    thresholds = (
+        (1_000_000_000, "B"),
+        (1_000_000, "M"),
+        (1_000, "K"),
+    )
+    for threshold, suffix in thresholds:
+        if value >= threshold:
+            return f"{value / threshold:.2f}{suffix}"
+    return str(value)
+
+
+def _format_file_size(size_bytes: int) -> str:
+
+    if size_bytes < 1024:
+        return f"`{size_bytes} B`"
+
+    units = ("KiB", "MiB", "GiB", "TiB")
+    value = float(size_bytes)
+    for unit in units:
+        value /= 1024
+        if value < 1024 or unit == units[-1]:
+            return f"`{value:.2f} {unit}` ({size_bytes:,} bytes)"
+    return f"`{size_bytes:,} bytes`"
+
+
+def _looks_like_hash(value: str) -> bool:
+
+    return bool(re.fullmatch(r"[0-9a-fA-F]{16,}", value))

llm_sbom/web/static/app.css

@@ -468,6 +468,41 @@ select:focus,
   max-height: 740px;
 }
 
+.hf-options {
+  margin-top: 20px;
+  padding: 18px 20px;
+  border-radius: 20px;
+  background: rgba(255, 255, 255, 0.03);
+  border: 1px solid rgba(154, 178, 255, 0.12);
+}
+
+.hf-options-note {
+  margin: 6px 0 16px;
+  color: var(--muted);
+  font-size: 0.88rem;
+  line-height: 1.5;
+}
+
+.hf-fields {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
+  gap: 14px;
+}
+
+input[type="number"] {
+  width: 100%;
+  padding: 14px 16px;
+  border-radius: 16px;
+  color: var(--text);
+  background: var(--card-strong);
+  border: 1px solid rgba(154, 178, 255, 0.12);
+}
+
+input[type="number"]:focus {
+  outline: 2px solid rgba(150, 240, 255, 0.85);
+  outline-offset: 2px;
+}
+
 @media (max-width: 1120px) {
   .controls,
   .browser {

llm_sbom/web/static/app.js

@@ -33,6 +33,12 @@ const elements = {
   tabButtons: Array.from(document.querySelectorAll("[data-tab]")),
   overviewTab: document.querySelector("#overview-tab"),
   rawTab: document.querySelector("#raw-tab"),
+  hfOptions: document.querySelector("#hf-options"),
+  hfTitle: document.querySelector("#hf-title"),
+  hfShortDescription: document.querySelector("#hf-short-description"),
+  hfSdk: document.querySelector("#hf-sdk"),
+  hfAppFile: document.querySelector("#hf-app-file"),
+  hfAppPort: document.querySelector("#hf-app-port"),
 };
 
 boot().catch((error) => {
@@ -112,12 +118,14 @@ function bindEvents() {
       return;
     }
 
-    const extension = state.currentFormat === "json" ? "json" : "txt";
+    const filename = state.currentFormat === "hf-readme"
+      ? "README.md"
+      : `L-BOM.${state.currentFormat === "json" ? "json" : "txt"}`;
     const blob = new Blob([state.renderedOutput], { type: "text/plain;charset=utf-8" });
     const url = URL.createObjectURL(blob);
     const link = document.createElement("a");
     link.href = url;
-    link.download = `L-BOM.${extension}`;
+    link.download = filename;
     document.body.append(link);
     link.click();
     link.remove();
@@ -128,6 +136,7 @@ function bindEvents() {
     button.addEventListener("click", () => {
       state.currentFormat = button.dataset.format;
       syncFormatButtons();
+      elements.hfOptions.hidden = state.currentFormat !== "hf-readme";
     });
   }
 
@@ -188,16 +197,32 @@ async function runScan() {
   setBusy(true);
 
   try {
+    const body = {
+      path,
+      format: state.currentFormat,
+      compute_hash: elements.hashToggle.checked,
+    };
+
+    if (state.currentFormat === "hf-readme") {
+      const hfTitle = elements.hfTitle.value.trim();
+      const hfShortDescription = elements.hfShortDescription.value.trim();
+      const hfSdk = elements.hfSdk.value;
+      const hfAppFile = elements.hfAppFile.value.trim();
+      const hfAppPortRaw = elements.hfAppPort.value.trim();
+
+      if (hfTitle) body.hf_title = hfTitle;
+      if (hfShortDescription) body.hf_short_description = hfShortDescription;
+      if (hfSdk) body.hf_sdk = hfSdk;
+      if (hfAppFile) body.hf_app_file = hfAppFile;
+      if (hfAppPortRaw) body.hf_app_port = parseInt(hfAppPortRaw, 10);
+    }
+
     const payload = await fetchJson("/api/scan", {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
       },
-      body: JSON.stringify({
-        path,
-        format: state.currentFormat,
-        compute_hash: elements.hashToggle.checked,
-      }),
+      body: JSON.stringify(body),
     });
 
     state.selectedPath = payload.selected_path;

llm_sbom/web/templates/index.html

@@ -51,6 +51,7 @@
               <button class="segment active" data-format="json" type="button">JSON</button>
               <button class="segment" data-format="spdx" type="button">SPDX</button>
               <button class="segment" data-format="table" type="button">Table</button>
+              <button class="segment" data-format="hf-readme" type="button">HF Readme</button>
             </div>
           </div>
 
@@ -66,6 +67,38 @@
           <button id="copy-path" class="ghost-button" type="button">Copy path</button>
         </div>
 
+        <div id="hf-options" class="hf-options" hidden>
+          <p class="eyebrow">Hugging Face README options</p>
+          <p class="hf-options-note">HF Readme only supports a single model file. All fields below are optional overrides.</p>
+          <div class="hf-fields">
+            <label class="field">
+              <span class="field-label">Title</span>
+              <input id="hf-title" type="text" placeholder="Inferred from model metadata" autocomplete="off">
+            </label>
+            <label class="field">
+              <span class="field-label">Short description</span>
+              <input id="hf-short-description" type="text" placeholder="Inferred from model metadata" autocomplete="off">
+            </label>
+            <label class="field">
+              <span class="field-label">SDK</span>
+              <select id="hf-sdk">
+                <option value="">None</option>
+                <option value="gradio">gradio</option>
+                <option value="docker">docker</option>
+                <option value="static">static</option>
+              </select>
+            </label>
+            <label class="field">
+              <span class="field-label">App file</span>
+              <input id="hf-app-file" type="text" placeholder="e.g. app.py or index.html" autocomplete="off">
+            </label>
+            <label class="field">
+              <span class="field-label">App port</span>
+              <input id="hf-app-port" type="number" placeholder="Docker only" min="1" max="65535" autocomplete="off">
+            </label>
+          </div>
+        </div>
+
         <div id="message" class="message" hidden></div>
       </section>
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "L-BOM"
-version = "0.1.0"
+version = "0.2.0"
 description = "Generate Software Bill of Materials documents for local LLM model files."
 readme = "README.md"
 requires-python = ">=3.10"

style.css

@@ -46,6 +46,48 @@ p {
 	color: #cbd5e1;
 }
 
+.link-grid {
+	display: flex;
+	flex-wrap: wrap;
+	gap: 12px;
+	margin: 8px 0 20px;
+}
+
+.link-chip {
+	display: inline-flex;
+	align-items: center;
+	justify-content: center;
+	min-height: 48px;
+	padding: 0.85rem 1.2rem;
+	border: 1px solid rgba(125, 211, 252, 0.38);
+	border-radius: 14px;
+	font-weight: 600;
+	letter-spacing: 0.01em;
+	color: #f8fafc;
+	background: linear-gradient(180deg, rgba(14, 165, 233, 0.34), rgba(8, 47, 73, 0.88));
+	box-shadow:
+		0 10px 24px rgba(8, 47, 73, 0.32),
+		inset 0 1px 0 rgba(255, 255, 255, 0.12),
+		inset 0 -1px 0 rgba(12, 74, 110, 0.4);
+	transition: background-color 160ms ease, border-color 160ms ease, color 160ms ease, transform 160ms ease;
+}
+
+.link-chip:hover,
+.link-chip:focus-visible {
+	border-color: rgba(186, 230, 253, 0.65);
+	background: linear-gradient(180deg, rgba(56, 189, 248, 0.46), rgba(12, 74, 110, 0.95));
+	color: #f8fafc;
+	text-decoration: none;
+	transform: translateY(-2px);
+}
+
+.link-chip:active {
+	transform: translateY(0);
+	box-shadow:
+		0 6px 14px rgba(8, 47, 73, 0.28),
+		inset 0 1px 0 rgba(255, 255, 255, 0.08);
+}
+
 .card p:last-child {
 	margin-bottom: 0;
 }
@@ -80,4 +122,12 @@ a:focus-visible {
 		padding: 24px 20px;
 		border-radius: 20px;
 	}
+
+	.link-grid {
+		gap: 10px;
+	}
+
+	.link-chip {
+		width: 100%;
+	}
 }

tests/test_cli.py

@@ -1,8 +1,12 @@
+from typing import Any
+
 from click.testing import CliRunner
 
 import llm_sbom.gui as gui_module
 from llm_sbom import __version__
 from llm_sbom.cli import main
+from llm_sbom.huggingface import HuggingFaceReadmeOptions, render_huggingface_readme
+from llm_sbom.schema import SBOMDocument
 
 
 def test_version_command_prints_package_version() -> None:
@@ -24,6 +28,110 @@ def test_scan_empty_directory_table_output() -> None:
     assert "No model files found." in result.output
 
 
+def test_render_hf_readme_infers_curated_metadata() -> None:
+    document = _sample_document()
+
+    rendered = render_huggingface_readme(document, HuggingFaceReadmeOptions())
+
+    assert 'title: "LFM2.5-1.2B-Instruct-Q8_0"' in rendered
+    assert "tags:" in rendered
+    assert '  - "liquid"' in rendered
+    assert '  - "gguf"' in rendered
+    assert "This README content was generated by `L-BOM`" in rendered
+    assert "- **License:** `lfm1.0`" in rendered
+    assert "- **Languages:** `en`, `fr`" in rendered
+    assert "tokenizer.chat_template" not in rendered
+
+
+def test_render_hf_readme_honors_overrides() -> None:
+    document = _sample_document()
+
+    rendered = render_huggingface_readme(
+        document,
+        HuggingFaceReadmeOptions(
+            title="LocalFusion Demo",
+            sdk="static",
+            app_file="index.html",
+            short_description="Custom summary",
+        ),
+    )
+
+    assert 'title: "LocalFusion Demo"' in rendered
+    assert 'sdk: "static"' in rendered
+    assert 'app_file: "index.html"' in rendered
+    assert 'short_description: "Custom summary"' in rendered
+    assert "# LocalFusion Demo" in rendered
+
+
+def test_render_hf_readme_includes_warnings() -> None:
+    document = _sample_document(warnings=["Quantization may need review."])
+
+    rendered = render_huggingface_readme(document, HuggingFaceReadmeOptions())
+
+    assert "## Warnings" in rendered
+    assert "- Quantization may need review." in rendered
+
+
+def test_scan_hf_readme_rejects_multi_model_directory() -> None:
+    runner = CliRunner()
+
+    with runner.isolated_filesystem():
+        with open("one.gguf", "wb") as handle:
+            handle.write(b"bad")
+        with open("two.gguf", "wb") as handle:
+            handle.write(b"bad")
+
+        result = runner.invoke(main, ["scan", ".", "--format", "hf-readme"])
+
+    assert result.exit_code != 0
+    assert "single model file at a time" in result.output
+
+
+def _sample_document(**overrides: object) -> SBOMDocument:
+    values: dict[str, Any] = {
+        "sbom_version": "1.0",
+        "generated_at": "2026-03-25T04:07:53.262551+00:00",
+        "tool_name": "l-bom",
+        "tool_version": "0.2.0",
+        "model_path": r"C:\models\LFM2.5-1.2B-Instruct-GGUF\LFM2.5-1.2B-Instruct-Q8_0.gguf",
+        "model_filename": "LFM2.5-1.2B-Instruct-Q8_0.gguf",
+        "file_size_bytes": 1246253888,
+        "sha256": "f6b981dcb86917fa463f78a362320bd5e2dc45445df147287eedb85e5a30d26a",
+        "format": "gguf",
+        "architecture": "lfm2",
+        "parameter_count": 1170340608,
+        "quantization": "Q5_1",
+        "dtype": None,
+        "context_length": 128000,
+        "vocab_size": 65536,
+        "license": None,
+        "base_model": None,
+        "training_framework": None,
+        "metadata": {
+            "general.name": "4cd563d5a96af9e7c738b76cd89a0a200db7608f",
+            "general.size_label": "1.2B",
+            "general.license": "other",
+            "general.license.name": "lfm1.0",
+            "general.license.link": "LICENSE",
+            "general.tags": ["liquid", "text-generation"],
+            "general.languages": ["en", "fr"],
+            "tokenizer.chat_template": "huge value that should not leak into the README",
+        },
+        "warnings": [],
+    }
+    values.update(overrides)
+    return SBOMDocument(**values)
+
+def test_scan_empty_directory_table_output() -> None:
+    runner = CliRunner()
+
+    with runner.isolated_filesystem():
+        result = runner.invoke(main, ["scan", ".", "--format", "table"])
+
+    assert result.exit_code == 0
+    assert "No model files found." in result.output
+
+
 def test_gui_command_dispatches_to_server_launcher(monkeypatch) -> None:
     runner = CliRunner()
     captured: dict[str, object] = {}