laminate-cli 0.1.0__py3-none-any.whl

laminate/categorize.py

@@ -0,0 +1,280 @@
+import json
+import logging
+
+from typing import Callable, Literal
+
+from pydantic import BaseModel
+
+from .gitlog import Commit
+from .llm import get_llm
+
+logger = logging.getLogger(__name__)
+
+Category = Literal["Added", "Changed", "Deprecated", "Removed", "Fixed", "Security"]
+
+DEFAULT_BATCH_SIZE = 15
+
+SYSTEM_PROMPT = """You are a precise changelog generator.
+
+You will be given a numbered list of raw git commit subjects.
+
+Your job is to turn these commits into concise, human-readable changelog entries.
+
+Related commits may be GROUPED together when they describe the same user-facing
+change, feature, bug fix, or piece of functionality. A group can contain one
+or multiple commits.
+
+Do not group unrelated changes merely because they are similar in implementation.
+
+Prefer a small number of meaningful changelog entries over one entry per commit.
+Intermediate implementation commits, refactors, tests, and small follow-up fixes
+may be grouped with the larger change they belong to.
+
+For each changelog entry, produce:
+
+- "category": exactly one of "Added", "Changed", "Deprecated", "Removed", "Fixed" or "Security"
+- "description": a short, human-readable rewrite of the grouped commits,
+  written for someone reading a changelog rather than a git log
+- "commits": a list of the input commit numbers belonging to this entry
+
+Category definitions:
+- Added: a new feature, capability, command, option, or user-facing functionality
+- Changed: a modification to existing behavior or functionality
+- Deprecated: functionality being phased out or marked for future removal
+- Removed: functionality that has been removed
+- Fixed: a bug fix or correction to broken behavior
+- Security: a security vulnerability fix or security-related change
+
+For descriptions:
+- no ticket numbers
+- no "fix:" or "feat:" prefixes
+- plain sentence case
+- describe the user-facing result rather than implementation details
+
+Every input commit number must appear in exactly one group.
+Do not omit commits.
+Do not duplicate commit numbers.
+
+Respond with ONLY a JSON array.
+No markdown fences, no commentary, and no extra text before or after the array.
+
+Example:
+
+[
+  {
+    "category": "Added",
+    "description": "Added user authentication and OAuth support.",
+    "commits": [1, 2, 4]
+  },
+  {
+    "category": "Fixed",
+    "description": "Fixed authentication callback handling.",
+    "commits": [3]
+  }
+]
+"""
+
+
+class CategorizedEntry(BaseModel):
+    category: Category
+    description: str
+
+
+class CategorizeError(Exception):
+    """Raised when a batch can't be categorized at all."""
+
+    pass
+
+
+def _chunk(items: list, size: int) -> list[list]:
+    return [items[i:i + size] for i in range(0, len(items), size)]
+
+
+def _build_prompt(commits: list[Commit]) -> str:
+    lines = [
+        f"{i + 1}. {c.subject}"
+        for i, c in enumerate(commits)
+    ]
+    return "\n".join(lines)
+
+
+def _strip_fences(text: str) -> str:
+    """Prevents the model from adding markdown fences around the JSON."""
+    text = text.strip()
+
+    if text.startswith("```"):
+        newline_idx = text.find("\n")
+        if newline_idx != -1:
+            text = text[newline_idx + 1:]
+        else:
+            text = text[3:]
+
+    if text.endswith("```"):
+        text = text.rsplit("```", 1)[0]
+
+    return text.strip()
+
+
+def _fallback_entries(commits: list[Commit]) -> list[CategorizedEntry]:
+    return [
+        CategorizedEntry(
+            category="Changed",
+            description=c.subject,
+        )
+        for c in commits
+    ]
+
+
+def _categorize_batch(
+    commits: list[Commit],
+    llm,
+) -> list[CategorizedEntry]:
+    """Categorize and intelligently group a batch of commits."""
+
+    prompt = _build_prompt(commits)
+
+    try:
+        response = llm.create_chat_completion(
+            messages=[
+                {"role": "system", "content": SYSTEM_PROMPT},
+                {"role": "user", "content": prompt},
+            ],
+            temperature=0.3,
+        )
+
+        text = response["choices"][0]["message"]["content"]
+
+    except Exception as e:
+        logger.warning(f"LLM error: {e}")
+        return _fallback_entries(commits)
+
+    text = _strip_fences(text)
+
+    try:
+        parsed = json.loads(text)
+
+    except json.JSONDecodeError as e:
+        logger.warning(f"Invalid JSON: {e}")
+        return _fallback_entries(commits)
+
+    if not isinstance(parsed, list):
+        logger.warning(
+            f"Expected list, got {type(parsed).__name__}"
+        )
+        return _fallback_entries(commits)
+
+    entries: list[CategorizedEntry] = []
+    used_commits: set[int] = set()
+
+    for item in parsed:
+        try:
+            category = item["category"]
+            description = item["description"]
+            commit_indices = item["commits"]
+
+            if not isinstance(commit_indices, list):
+                raise ValueError("commits must be a list")
+
+            if not commit_indices:
+                raise ValueError("commits list cannot be empty")
+
+            normalized_indices = []
+
+            for index in commit_indices:
+                if not isinstance(index, int):
+                    raise ValueError(
+                        f"commit index must be an integer, got {index!r}"
+                    )
+
+                if not 1 <= index <= len(commits):
+                    raise ValueError(
+                        f"commit index {index} is out of range"
+                    )
+
+                if index in used_commits:
+                    raise ValueError(
+                        f"commit {index} appears in multiple groups"
+                    )
+
+                normalized_indices.append(index)
+
+            entry = CategorizedEntry(
+                category=category,
+                description=description,
+            )
+
+            entries.append(entry)
+            used_commits.update(normalized_indices)
+
+        except (KeyError, ValueError, TypeError) as e:
+            logger.warning(f"Invalid grouped entry: {e}")
+            continue
+
+    missing_commits = [
+        i
+        for i in range(1, len(commits) + 1)
+        if i not in used_commits
+    ]
+
+    if missing_commits:
+        logger.info(
+            f"Model omitted {len(missing_commits)} commits; "
+            "using fallback entries for them"
+        )
+
+        for index in missing_commits:
+            entries.append(
+                CategorizedEntry(
+                    category="Changed",
+                    description=commits[index - 1].subject,
+                )
+            )
+
+    if not entries:
+        return _fallback_entries(commits)
+
+    return entries
+
+
+def categorize_commits(
+    commits: list[Commit],
+    batch_size: int = DEFAULT_BATCH_SIZE,
+    on_progress: Callable[[int, int, int], None] | None = None,
+) -> list[CategorizedEntry]:
+    if not commits:
+        return []
+
+    llm = get_llm()
+    all_entries: list[CategorizedEntry] = []
+    batches = _chunk(commits, batch_size)
+
+    for i, batch in enumerate(batches):
+        if on_progress:
+            on_progress(
+                i + 1,
+                len(batches),
+                len(batch),
+            )
+
+        all_entries.extend(
+            _categorize_batch(batch, llm)
+        )
+
+    return all_entries
+
+# testing purposes only
+if __name__ == "__main__":
+    from .gitlog import get_commits
+
+    commits = get_commits()[:15]
+
+    if not commits:
+        print("No commits found in current directory.")
+    else:
+        print(f"Categorizing {len(commits)} commits...\n")
+        results = categorize_commits(commits)
+        for entry in results:
+            print(
+                f"[{entry.category}] "
+                f"{entry.description}"
+            )

laminate/cli.py

@@ -0,0 +1,91 @@
+import typer
+
+from concurrent.futures import ThreadPoolExecutor
+
+import sys
+
+from rich.console import Console
+from rich.live import Live
+from rich.spinner import Spinner
+
+from .gitlog import get_commits, GitLogError
+from .categorize import categorize_commits
+from .llm import LLMError
+from .render import render_changelog, write_changelog
+
+app = typer.Typer(add_completion=False)
+console = Console()
+
+
+@app.command()
+def generate(
+    repo: str = typer.Option(".", help="Path to the git repository."),
+    since: str = typer.Option(None, help="Only include commits after this date, e.g. 2026-01-01."),
+    until: str = typer.Option(None, help="Only include commits before this date, e.g. 2026-01-01."),
+    commit_range: str = typer.Option(None, "--range", help="A git commit range, e.g. v1.0.0..v1.1.0. Overrides --since/--until."),
+    output: str = typer.Option("CHANGELOG.md", help="Path to write the generated changelog to."),
+    batch_size: int = typer.Option(15, "--batch-size", help="Number of commits sent to the LLM per batch."),
+    release: str = typer.Option(None, "--release", help="Version number for this release, e.g. 1.1.0. If omitted, the changelog is headed [Unreleased]."),
+):
+    if repo != ".":
+        typer.echo(f"Reading commits from '{repo}'...")
+    else:
+        typer.echo("Reading commits from working directory...")
+
+
+    try:
+        commits = get_commits(
+            repo_path=repo,
+            since=since,
+            until=until,
+            commit_range=commit_range,
+        )
+    except GitLogError as e:
+        typer.echo(f"Error reading git log: {e}", err=True)
+        raise typer.Exit(code=1)
+
+    if not commits:
+        typer.echo("No commits found for the given range - nothing to do.")
+        raise typer.Exit(code=0)
+
+    console.print(f"Found {len(commits)} commits.")
+
+    try:
+        spinner = Spinner(
+            "dots",
+            text="Categorizing commits with the local model...",
+        )
+
+        def progress(current, total, count):
+            spinner.update(
+                text=f"Categorizing commits... batch {current}/{total} ({count} commits)"
+            )
+
+        with Live(spinner, refresh_per_second=10):
+            with ThreadPoolExecutor(max_workers=1) as executor:
+                future = executor.submit(
+                    categorize_commits,
+                    commits,
+                    batch_size=batch_size,
+                    on_progress=progress,
+                )
+                entries = future.result()
+
+        console.print(f"✓ Categorized {len(commits)} commits.")
+
+    except LLMError as e:
+        typer.echo(
+            f"Error loading or running the local model: {e}",
+            err=True,
+        )
+        raise typer.Exit(code=1)
+
+    changelog = render_changelog(entries, version=release)
+    write_changelog(changelog, output)
+
+    typer.echo(f"\nDone. Changelog written to {output}", file=sys.stdout)
+
+
+
+if __name__ == "__main__":
+    app()

laminate/gitlog.py

@@ -0,0 +1,99 @@
+import subprocess
+from pydantic import BaseModel
+
+
+FIELD_SEP = "\x1f"
+RECORD_SEP = "\x1e"
+
+
+class Commit(BaseModel):
+    hash: str
+    short_hash: str
+    author: str
+    date: str  # ISO 8601, e.g. 2026-09-30T14:22:01-05:00
+    subject: str
+
+class GitLogError(Exception):
+    pass
+
+def get_commits(
+    repo_path: str = ".",
+    since: str | None = None,
+    until: str | None = None,
+    commit_range: str | None = None,
+) -> list[Commit]:
+    """
+    Returns commits from the given repo, newest first.
+
+    repo_path: path to the git repository (defaults to current directory)
+    since / until: date bounds, e.g. since="2026-01-01"
+    commit_range: a git revision range, e.g. "v1.0.0..v1.1.0" - if given,
+        this takes priority over since/until
+
+    Raises GitLogError if the path isn't a git repo, the range is
+    invalid, or git itself isn't installed/on PATH.
+    """
+    pretty_format = FIELD_SEP.join(["%H", "%h", "%an", "%aI", "%s"]) + RECORD_SEP
+
+    cmd = ["git", "-C", repo_path, "log", f"--pretty=format:{pretty_format}"]
+
+    if commit_range:
+        cmd.append(commit_range)
+    else:
+        if since:
+            cmd.append(f"--since={since}")
+        if until:
+            cmd.append(f"--until={until}")
+
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+    except FileNotFoundError:
+        raise GitLogError(
+            "git doesn't appear to be installed, or isn't on your PATH."
+        )
+    except subprocess.CalledProcessError as e:
+        raise GitLogError(
+            f"git log failed (is '{repo_path}' a git repo, and is the "
+            f"commit range valid?): {e.stderr.strip()}"
+        )
+
+    raw_output = result.stdout
+    if not raw_output.strip():
+        return []
+
+    commits = []
+    for record in raw_output.split(RECORD_SEP):
+        record = record.strip()
+        if not record:
+            continue
+
+        fields = record.split(FIELD_SEP)
+        if len(fields) != 5:
+            continue
+
+        full_hash, short_hash, author, date, subject = fields
+        commits.append(
+            Commit(
+                hash=full_hash,
+                short_hash=short_hash,
+                author=author,
+                date=date,
+                subject=subject,
+            )
+        )
+
+    return commits
+
+# testing purposes only
+if __name__ == "__main__":
+    commits = get_commits()
+    print(f"Found {len(commits)} commits:\n")
+    for c in commits[:10]:
+        print(f"{c.short_hash}  {c.date}  {c.author}: {c.subject}")
+    if len(commits) > 10:
+        print(f"... and {len(commits) - 10} more")

laminate/llm.py

@@ -0,0 +1,95 @@
+from pathlib import Path
+from llama_cpp import Llama
+
+MODELS_DIR = Path(__file__).resolve().parent.parent / "models"
+
+DEFAULT_N_CTX = 4096  
+_llm: Llama | None = None
+
+
+class LLMError(Exception):
+    pass
+
+
+def _find_model_file() -> Path:
+    if not MODELS_DIR.exists():
+        raise LLMError(
+            f"Models folder not found at {MODELS_DIR}. Create it and "
+            "place a .gguf model file inside (see README for a "
+            "recommended model and download link)."
+        )
+
+    gguf_files = list(MODELS_DIR.glob("*.gguf"))
+
+    if not gguf_files:
+        raise LLMError(
+            f"No .gguf model file found in {MODELS_DIR}. Download a "
+            "compatible model (see README) and place it in that folder."
+        )
+
+    if len(gguf_files) > 1:
+        names = ", ".join(f.name for f in gguf_files)
+        raise LLMError(
+            f"Multiple .gguf files found in {MODELS_DIR} ({names}) - "
+            "keep only one so Laminate knows which to load."
+        )
+
+    return gguf_files[0]
+
+
+def get_llm(n_ctx: int = DEFAULT_N_CTX) -> Llama:
+    global _llm
+
+    if _llm is None:
+        model_path = _find_model_file()
+        try:
+            _llm = Llama(
+                model_path=str(model_path),
+                n_ctx=n_ctx,
+                verbose=False,
+            )
+        except Exception as e:
+            raise LLMError(f"Failed to load model at {model_path}: {e}")
+
+    return _llm
+
+
+def generate(
+    prompt: str,
+    system_prompt: str | None = None,
+    max_tokens: int = 512,
+    temperature: float = 0.3,
+) -> str:
+    """
+    Sends a prompt to the local model and returns its text response.
+
+    system_prompt: optional instruction framing the model's role/task
+        (e.g. "You are a precise changelog generator...")
+    temperature: kept low by default (0.3) to prevent rambling. Increase the temperature for more "creative" responses.
+    """
+    llm = get_llm()
+
+    messages = []
+    if system_prompt:
+        messages.append({"role": "system", "content": system_prompt})
+    messages.append({"role": "user", "content": prompt})
+
+    response = llm.create_chat_completion(
+        messages=messages,
+        max_tokens=max_tokens,
+        temperature=temperature,
+    )
+
+    return response["choices"][0]["message"]["content"].strip()
+
+# testing purposes only
+if __name__ == "__main__":
+    print("Loading model...")
+    get_llm()
+    print("Model loaded. Sending a test prompt...\n")
+
+    reply = generate(
+        "Reply with exactly one short sentence confirming you're working.",
+        max_tokens=50,
+    )
+    print(f"Response: {reply}")

laminate/render.py

@@ -0,0 +1,71 @@
+from collections import defaultdict
+from datetime import date
+
+from .categorize import CategorizedEntry
+
+CATEGORY_ORDER = ["Added", "Changed", "Deprecated", "Removed", "Fixed", "Security"]
+
+
+def render_changelog(entries: list[CategorizedEntry], version: str | None = None) -> str:
+    """
+    Renders categorized entries into Keep a Changelog formatted
+    markdown.
+
+    version: if given, the header becomes "## [version] - today's date"
+        (for cutting an actual release). If omitted, defaults to the
+        standard "## [Unreleased]" header.
+    """
+    if version:
+        header = f"## [{version}] - {date.today().isoformat()}"
+    else:
+        header = "## [Unreleased]"
+
+    lines = [
+        "# Changelog",
+        "",
+        "All notable changes to this project will be documented in this file.",
+        "",
+        "The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), "
+        "and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).",
+        "",
+        header,
+        "",
+    ]
+
+    by_category: dict[str, list[str]] = defaultdict(list)
+    for entry in entries:
+        by_category[entry.category].append(entry.description)
+
+    for category in CATEGORY_ORDER:
+        if category not in by_category:
+            continue
+        lines.append(f"### {category}")
+        for desc in by_category[category]:
+            lines.append(f"- {desc}")
+        lines.append("")
+
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def write_changelog(content: str, output_path: str = "CHANGELOG.md") -> None:
+    with open(output_path, "w", encoding="utf-8") as f:
+        f.write(content)
+
+# testing purposes only
+if __name__ == "__main__":
+    
+    from .gitlog import get_commits
+    from .categorize import categorize_commits
+
+    commits = get_commits()[:10]
+
+    if not commits:
+        print("No commits found in current directory.")
+    else:
+        print(f"Categorizing {len(commits)} commits...\n")
+        entries = categorize_commits(commits)
+        changelog = render_changelog(entries)
+
+        print(changelog)
+        write_changelog(changelog)
+        print("Wrote changelog.md")

laminate_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,29 @@
+Metadata-Version: 2.4
+Name: laminate-cli
+Version: 0.1.0
+Summary: Generate release-ready changelogs from git history using a local LLM
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: llama-cpp-python
+Requires-Dist: pydantic
+Requires-Dist: typer
+Requires-Dist: rich
+Dynamic: license-file
+
+<div style="text-align: center;">
+    <img src="assets/laminate-logo.svg" alt="Laminate Logo" width=200>
+    <h1>Laminate</h1>
+    <h4><a href="https://apleut.dev">My Website</a> - <a href="changelog.md">Changelog</a></h4>
+    <hr></hr>
+</div>
+
+> [!NOTE]
+> Laminate is in **extremely early development.** Everything stated here is subject to change. If you want to contribute to Laminate, contact me via email at __me@apleut.dev__.
+
+> [!WARNING]
+> When installing requirements on Windows machines, make sure to install `llama-cpp-python` using this command first:
+> `pip install llama-cpp-python --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cpu`
+> Otherwise, the path lengths of the source code will be too long for Windows to handle, and it will raise an error.
+
+A CLI to write release-ready changelogs for you using llama-cpp-python.

laminate_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+laminate/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+laminate/categorize.py,sha256=YPkkT1GywPJENXY95anTxheoOWB5DmtO5s9lzXuaidQ,7630
+laminate/cli.py,sha256=4phL0uJBMaQst9FpdPBFteg5Duzt1qsax99wqKlKhCc,2959
+laminate/gitlog.py,sha256=dy5SGEvjYeL-5U6CZ2popTr8fbfnWWG0VcZAdgfj9po,2657
+laminate/llm.py,sha256=ykzT1jyxGLtHNaG7cPx6AbIoh6lLdamhxLBKBdqzv_0,2602
+laminate/render.py,sha256=nNZfF-J7LhI9UhICOy_pw66-wQfRdMNcEkr1XrJschM,2169
+laminate_cli-0.1.0.dist-info/licenses/LICENSE,sha256=YF6QR6Vjxcg5b_sYIyqkME7FZYau5TfEUGTG-0JeRK0,35129
+laminate_cli-0.1.0.dist-info/METADATA,sha256=tlQOZEMSM_hfksp6g3_EgcZfD_Obw2lPyB4JjC3c2HE,1196
+laminate_cli-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+laminate_cli-0.1.0.dist-info/entry_points.txt,sha256=uY2f2xhLPxYDUagcq3qBB0K6pD3DmFZnMxbINJ3QeSY,46
+laminate_cli-0.1.0.dist-info/top_level.txt,sha256=GSm5tt407xo7z7F-vi6xxgNZzAXCDwOEFh-OxTWKrJw,9
+laminate_cli-0.1.0.dist-info/RECORD,,

laminate_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

laminate_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+laminate = laminate.cli:app