git-cai-cli 0.1.1.dev0__py3-none-any.whl

git_cai_cli/cli.py

@@ -0,0 +1,61 @@
+"""
+Main function
+"""
+
+import logging
+import subprocess
+import sys
+from pathlib import Path
+
+from git_cai_cli.core.config import get_default_config, load_config, load_token
+from git_cai_cli.core.gitutils import find_git_root, git_diff_excluding
+from git_cai_cli.core.llm import CommitMessageGenerator
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(levelname)s: %(message)s",
+)
+log = logging.getLogger(__name__)
+
+
+def main() -> None:
+    """
+    Check for git repo, load access tokens and run git cai
+    """
+    # Ensure invoked as 'git cai'
+    invoked_as = Path(sys.argv[0]).name
+    if not invoked_as.startswith("git-"):
+        print("This command must be run as 'git cai'", file=sys.stderr)
+        sys.exit(1)
+
+    # Find the git repo root
+    repo_root = find_git_root()
+    if not repo_root:
+        log.error("Not inside a Git repository.")
+        sys.exit(1)
+
+    # Load configuration and token
+    config = load_config()
+    default_model = get_default_config()
+    log.debug("Default model from config: %s", default_model)
+    token = load_token(default_model)
+    if not token:
+        log.error("Missing %s token in ~/.config/cai/tokens.yml", default_model)
+        sys.exit(1)
+
+    # Get git diff
+    diff = git_diff_excluding(repo_root)
+    if not diff.strip():
+        log.info("No changes to commit. Did you run 'git add'? Files must be staged.")
+        sys.exit(0)
+
+    # Generate commit message
+    generator = CommitMessageGenerator(token, config, default_model)
+    commit_message = generator.generate(diff)
+
+    # Open git commit editor with the generated message
+    subprocess.run(["git", "commit", "--edit", "-m", commit_message], check=True)
+
+
+if __name__ == "__main__":
+    main()

git_cai_cli/core/config.py

@@ -0,0 +1,146 @@
+"""
+Set configuration
+"""
+
+import logging
+import os
+import stat
+from pathlib import Path
+from typing import Any, Optional
+
+import yaml
+from git_cai_cli.core.gitutils import find_git_root
+
+log = logging.getLogger(__name__)
+
+CONFIG_DIR = Path.home() / ".config" / "cai"
+FALLBACK_CONFIG_FILE = CONFIG_DIR / "cai_config.yml"
+TOKENS_FILE = CONFIG_DIR / "tokens.yml"
+
+DEFAULT_CONFIG = {
+    "openai": {"model": "gpt-4.1", "temperature": 0},
+    "gemini": {"model": "gemini-2.5-flash", "temperature": 0},
+    "default": "openai",
+}
+
+TOKEN_TEMPLATE = {
+    "openai": "PUT-YOUR-OPENAI-TOKEN-HERE",
+    "gemini": "PUT-YOUR-GEMINI-TOKEN-HERE",
+}
+
+
+def load_config(
+    fallback_config_file: Path = FALLBACK_CONFIG_FILE,
+    default_config: Optional[dict[str, Any]] = None,
+) -> dict[str, Any]:
+    """
+    Load configuration of LLM
+    """
+    if default_config is None:
+        default_config = DEFAULT_CONFIG.copy()
+    log.debug("Loading config...")
+
+    repo_root = find_git_root()
+    repo_config_file = Path(repo_root) / "cai_config.yml" if repo_root else None
+
+    if repo_config_file and repo_config_file.exists():
+        try:
+            with open(repo_config_file, "r", encoding="utf-8") as f:
+                config = yaml.safe_load(f) or {}
+            if config:
+                return config
+        except yaml.YAMLError as e:
+            log.error("Failed to parse repo config: %s", e)
+
+    if not fallback_config_file.exists() or fallback_config_file.stat().st_size == 0:
+        log.warning(
+            "No config file provided and default config missing or empty. Creating default config in %s",
+            fallback_config_file,
+        )
+        fallback_config_file.parent.mkdir(parents=True, exist_ok=True)
+        with open(fallback_config_file, "w", encoding="utf-8") as f:
+            yaml.safe_dump(default_config, f)
+        return default_config
+
+    try:
+        with open(fallback_config_file, "r", encoding="utf-8") as f:
+            return yaml.safe_load(f) or default_config
+    except yaml.YAMLError as e:
+        log.error("Failed to parse config at %s: %s", fallback_config_file, e)
+        return default_config
+
+
+def load_token(
+    key_name: str,
+    tokens_file: Path = TOKENS_FILE,
+    token_template: Optional[dict[str, Any]] = None,
+) -> str | None:
+    """
+    Load token to connecto to LLM
+    """
+    if token_template is None:
+        token_template = TOKEN_TEMPLATE.copy()
+    log.debug("Loading token...")
+    tokens_file.parent.mkdir(parents=True, exist_ok=True)
+
+    if not tokens_file.exists():
+        log.debug("Check whether file containing tokens exist")
+        log.warning("%s does not exist. Creating a token template file.", tokens_file)
+        with open(tokens_file, "w", encoding="utf-8") as f:
+            yaml.safe_dump(token_template, f)
+        os.chmod(tokens_file, stat.S_IRUSR | stat.S_IWUSR)
+        log.info("Created token template at %s", tokens_file)  # nosemgrep
+        return None
+
+    try:
+        with open(tokens_file, "r", encoding="utf-8") as f:
+            tokens = yaml.safe_load(f) or {}
+    except yaml.YAMLError as e:
+        log.error("Error parsing %s: %s", tokens_file, e)
+        return None
+
+    if key_name not in tokens:
+        log.error("Key '%s' not found in %s.", key_name, tokens_file)
+        return None
+
+    return tokens[key_name]
+
+
+def get_default_config() -> str:
+    """
+    Looks for cai_config.yml in the repo root,
+    else in ~/.config/cai/cai_config.yml.
+    Returns the value of the 'default' key if it exists.
+    Raises FileNotFoundError or KeyError otherwise.
+    """
+    repo_root = find_git_root()
+    repo_config = repo_root / "cai_config.yml" if repo_root else None
+    home_config = Path.home() / ".config" / "cai" / "cai_config.yml"
+
+    if repo_config and repo_config.is_file():
+        config_path = repo_config
+        log.info("Using config file from repo root: %s", config_path)
+    elif home_config.is_file():
+        config_path = home_config
+        log.info("Using config file from user config dir: %s", config_path)
+    else:
+        log.error("No cai_config.yml found in repo root or %s", home_config)
+        raise FileNotFoundError(
+            f"No cai_config.yml found in repo root or {home_config}"
+        )
+
+    try:
+        with config_path.open("r", encoding="utf-8") as f:
+            config = yaml.safe_load(f) or {}
+            log.debug("Loaded configuration from %s: %s", config_path, config)
+    except yaml.YAMLError as e:
+        log.exception("Error parsing YAML file %s", config_path)
+        raise ValueError(f"Error parsing YAML file {config_path}: {e}") from e
+
+    if "default" not in config:
+        log.error("'default' key not found in %s", config_path)
+        raise KeyError(f"'default' key not found in {config_path}")
+
+    default_value = config["default"]
+    log.info("Default config value: %s", default_value)
+    return default_value

git_cai_cli/core/gitutils.py

@@ -0,0 +1,57 @@
+"""
+Check git repo and run git diff
+"""
+
+import logging
+import subprocess
+import sys
+from pathlib import Path
+from typing import Callable
+
+log = logging.getLogger(__name__)
+
+
+def find_git_root(
+    run_cmd: Callable[..., subprocess.CompletedProcess] = subprocess.run,
+) -> Path | None:
+    """Returns the root directory of the current Git repository, or None if not in a Git repo."""
+    try:
+        result = run_cmd(
+            ["git", "rev-parse", "--show-toplevel"],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        return Path(result.stdout.strip())
+    except subprocess.CalledProcessError:
+        return None
+
+
+def git_diff_excluding(
+    repo_root: Path,
+    run_cmd: Callable[..., subprocess.CompletedProcess] = subprocess.run,
+    exit_func: Callable[[int], None] = sys.exit,
+) -> str:
+    """Run `git diff` excluding files listed in .caiignore."""
+    ignore_file = repo_root / ".caiignore"
+
+    exclude_files: list[str] = []
+    if ignore_file.exists():
+        with open(ignore_file, "r", encoding="utf-8") as f:
+            exclude_files = [
+                line.strip()
+                for line in f
+                if line.strip() and not line.strip().startswith("#")
+            ]
+        if not exclude_files:
+            log.info("%s is empty. No files excluded.", ignore_file)
+
+    cmd = ["git", "diff", "--cached", "--", "."]
+    cmd.extend(f":!{pattern}" for pattern in exclude_files)
+
+    result = run_cmd(cmd, capture_output=True, text=True, check=True)
+    if result.returncode != 0:
+        log.error("git diff failed: %s", result.stderr.strip())
+        exit_func(1)
+
+    return result.stdout

git_cai_cli/core/llm.py

@@ -0,0 +1,97 @@
+"""
+Settings and connection of LLM
+"""
+
+import logging
+from typing import Any, Dict, Type
+
+from google import genai  # type: ignore[reportUnknownImport]
+from google.genai import types  # type: ignore[reportUnknownImport]
+from openai import OpenAI
+
+log = logging.getLogger(__name__)
+
+
+class CommitMessageGenerator:
+    """
+    Generates git commit messages from a git diff using LLMs.
+    """
+
+    def __init__(self, token: str, config: Dict[str, Any], default_model: str):
+        self.token = token
+        self.config = config
+        self.default_model = default_model
+
+    def generate(self, git_diff: str) -> str:
+        """
+        Generate a commit message using the default model.
+        """
+        model_dispatch = {
+            "openai": self.generate_openai,
+            "gemini": self.generate_gemini,
+        }
+
+        try:
+            log.debug("Generating commit message using model '%s'", self.default_model)
+            return model_dispatch[self.default_model](git_diff)
+        except KeyError as e:
+            log.error("Unknown default model: '%s'", self.default_model)
+            raise ValueError(f"Unknown default model: '{self.default_model}'") from e
+
+    def _system_prompt(self) -> str:
+        """
+        Shared system prompt for both OpenAI and Gemini.
+        """
+        return (
+            "You are an expert software engineer assistant. "
+            "Your task is to generate a concise, professional git commit message "
+            "summarizing the provided git diff changes. "
+            "Keep the message clear and focused on what was changed and why. "
+            "Always include a headline, followed by a bullet-point list of changes."
+        )
+
+    def generate_openai(self, git_diff: str, openai_cls: Type[Any] = OpenAI) -> str:
+        """
+        Generate a commit message using OpenAI's API.
+        """
+        client = openai_cls(api_key=self.token)
+        model = self.config["openai"]["model"]
+        temperature = self.config["openai"]["temperature"]
+
+        system_prompt = self._system_prompt()
+
+        messages = [
+            {"role": "system", "content": system_prompt},
+            {
+                "role": "user",
+                "content": f"Generate a commit message for:\n\n{git_diff}",
+            },
+        ]
+
+        completion = client.chat.completions.create(
+            model=model,
+            messages=messages,
+            temperature=temperature,
+        )
+        return completion.choices[0].message.content.strip()
+
+    def generate_gemini(
+        self, git_diff: str, genai_cls: Type[Any] = genai.Client
+    ) -> str:
+        """
+        Generate a commit message using Gemini's API.
+        """
+        client = genai_cls(api_key=self.token)
+        model = self.config["gemini"]["model"]
+        temperature = self.config["gemini"]["temperature"]
+        system_prompt = self._system_prompt()
+        messages = git_diff
+        response = client.models.generate_content(
+            model=model,
+            contents=messages,
+            config=types.GenerateContentConfig(
+                system_instruction=system_prompt,
+                temperature=temperature,
+            ),
+        )
+        return response.text

git_cai_cli-0.1.1.dev0.dist-info/METADATA

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: git-cai-cli
+Version: 0.1.1.dev0
+Summary: Use LLM to create git commits
+Author-email: Thorsten Foltz <thorsten.foltz@live.com>
+License: MIT
+Project-URL: Homepage, https://github.com/thorstenfoltz/cai
+Project-URL: Issues, https://github.com/thorstenfoltz/cai/issues
+Keywords: Git,LLM,Commit,AI,GenAI
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Version Control
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: openai>=1.0
+Requires-Dist: google-genai>=1.41.0
+Dynamic: license-file
+
+# cai
+
+`cai` is a Git extension written in Python that automates commit message creation. It allows you to run `git cai` to automatically generate a commit message based on changes and new additions in your repository.  
+
+`cai` leverages a **large language model (LLM)** to generate meaningful and context-aware commit messages. Currently, it supports the **OpenAI** and **Gemini API** for generating commit messages.
+
+## Table of Contents
+
+- [About](#about-section)
+- [Prerequisites](#prerequisites)
+- [Features](#features-section)
+- [Installation](#installation-section)
+- [Usage](#usage-section)
+- [License](#license-section)
+
+<h2 id="about-section">About</h2>
+
+`cai` is designed to simplify your Git workflow by automatically generating commit messages using an LLM. No more struggling to summarize changes — `git cai` does it for you.  
+
+Currently, the only supported backend are the OpenAI and Gemini API, but additional LLM integrations may be added in the future.
+
+<h2 id="prerequisites">Prerequisites</h2>
+
+- Python 3.10 or higher
+- [Pipx](https://pypi.org/project/pipx/) or [Pip](https://pypi.org/project/pip/) if installed in a virtual environment
+- API key, currently supported
+  - OpenAI
+  - Gemini
+
+<h2 id="features-section">Features</h2>
+
+- Automatically detects added, modified, and deleted files
+- Generates meaningful commit messages using an LLM
+- Seamless integration with Git as a plugin/extension
+- Written in Python for easy customization
+
+<h2 id="installation-section">Installation</h2>
+
+Install by
+
+```sh
+pipx install git-cai-cli
+```
+
+Afterwards set cai to PATH by
+
+```sh
+pipx ensurepath
+```
+
+Restart your shell by executing `bash` or `zsh` or whatever else is your used shell.
+
+<h2 id="usage-section">Usage</h2>
+
+Once installed, you can use `cai` like a normal Git command:
+
+```sh
+git cai
+```
+
+`cai` automatically creates a configuration file at: `~/.config/cai/token.yml`
+This file stores your OpenAI API key, which is used every time you run `git cai`.
+Open `~/.config/cai/token.yml` and store your token from OpenAI.
+If a `cai_config.yml` file exists in the root of your repository, `cai` will use the settings defined there. Otherwise, it falls back to default settings, which are automatically created in the same directory as `token.yml` if they don’t already exist.
+Currently, the only configurable options are:
+
+- LLM model
+- Temperature
+
+`cai` uses Git’s `diff` output as input for generating commit messages.  
+To exclude specific files or directories from being included in the generated commit message, create a `.caiignore` file in the root of your repository. This file works like a `.gitignore`.  
+
+- Files listed in `.gitignore` are **always excluded**.  
+- `.caiignore` is only needed for files that are tracked by Git but should **not** be included in the commit message.
+
+<h2 id="license-section">License</h2>
+This project is licensed under the MIT License.

git_cai_cli-0.1.1.dev0.dist-info/RECORD

@@ -0,0 +1,13 @@
+git_cai_cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+git_cai_cli/cli.py,sha256=-uJibVFO4bseav5ylV7HXu17mvlr7vJX3MONQCIgDYE,1724
+git_cai_cli/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+git_cai_cli/core/config.py,sha256=oPHmtnuA3L0ZMfDgYSxvnAraKTd4x8GWYBAZnsO-fV8,4892
+git_cai_cli/core/gitutils.py,sha256=9nLxOr6Ug-xYu9PUNaZWpC7qfXYc0q4ve-l4vC4hi98,1671
+git_cai_cli/core/llm.py,sha256=d1jrLP9ssbEkWg22YJbJUZizSmbaE5MdCSeJ2uSYDUw,3215
+git_cai_cli-0.1.1.dev0.dist-info/licenses/LICENSE,sha256=mJXH267ubRO4gQIr_0QP42N7tqstouAmsEs5Na73z58,1071
+tests/test_core/test_config.py,sha256=ADmOH1bau2bwovp382m7rP64t1JL9J6xNDIv-Ato-WI,3934
+git_cai_cli-0.1.1.dev0.dist-info/METADATA,sha256=yXGChHmJMS8SAdWJhh9dCA6mCw9vt8iKm7EO_WSHZac,3917
+git_cai_cli-0.1.1.dev0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+git_cai_cli-0.1.1.dev0.dist-info/entry_points.txt,sha256=lNDzmy9McXaZcF-UFAQrfMleNX4DkUiljRp3_K8GV-w,49
+git_cai_cli-0.1.1.dev0.dist-info/top_level.txt,sha256=BGbckcfCHqxkzlMsUzkwZSTooOOJO7vqaIykiiCOR9U,18
+git_cai_cli-0.1.1.dev0.dist-info/RECORD,,

git_cai_cli-0.1.1.dev0.dist-info/WHEEL

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

git_cai_cli-0.1.1.dev0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+git-cai = git_cai_cli.cli:main

git_cai_cli-0.1.1.dev0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Thorsten Foltz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

git_cai_cli-0.1.1.dev0.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+git_cai_cli
+tests

tests/test_core/test_config.py

@@ -0,0 +1,128 @@
+"""
+Unit tests for git_cai_cli.core.config module.
+
+These tests cover the basic functionality of load_config and load_token,
+including file creation, reading existing files, repo config precedence,
+token retrieval, and handling missing keys.
+"""
+
+import stat
+from unittest.mock import patch
+
+import yaml
+from git_cai_cli.core.config import (
+    DEFAULT_CONFIG,
+    TOKEN_TEMPLATE,
+    load_config,
+    load_token,
+)
+
+# ------------------------------
+# LOAD CONFIG UNIT TESTS
+# ------------------------------
+
+
+def test_load_config_returns_default(tmp_path):
+    """
+    Test that load_config returns the default configuration when no fallback
+    or repo-level config exists, and that it creates the fallback file.
+    """
+    fallback_file = tmp_path / "cai_config.yml"
+    config = load_config(fallback_config_file=fallback_file)
+
+    # Should return the default configuration
+    assert config == DEFAULT_CONFIG
+
+    # Should create the fallback file
+    assert fallback_file.exists()
+
+
+def test_load_config_reads_existing_file(tmp_path):
+    """
+    Test that load_config correctly reads an existing fallback configuration file.
+    """
+    fallback_file = tmp_path / "cai_config.yml"
+    sample_config = {"openai": {"model": "gpt-3.5", "temperature": 0.7}}
+
+    # Write sample config to fallback file
+    fallback_file.write_text(yaml.safe_dump(sample_config))
+
+    # load_config should return the contents of the file
+    config = load_config(fallback_config_file=fallback_file)
+    assert config == sample_config
+
+
+def test_load_config_prefers_repo_config(tmp_path):
+    """
+    Test that load_config prefers a repo-level config over the fallback config.
+    """
+    # Create a repo-level config file
+    repo_file = tmp_path / "cai_config.yml"
+    repo_config = {"openai": {"model": "repo-model", "temperature": 1.0}}
+    repo_file.write_text(yaml.safe_dump(repo_config))
+
+    # Create a fallback file
+    fallback_file = tmp_path / "fallback.yml"
+    fallback_file.write_text(yaml.safe_dump(DEFAULT_CONFIG))
+
+    # Mock find_git_root to simulate a repo
+    with patch("git_cai_cli.core.config.find_git_root", return_value=tmp_path):
+        config = load_config(fallback_config_file=fallback_file)
+        assert config == repo_config
+
+
+# ------------------------------
+# LOAD TOKEN UNIT TESTS
+# ------------------------------
+
+
+def test_load_token_creates_template(tmp_path):
+    """
+    Test that load_token creates a template token file if none exists,
+    returns None, and sets correct file permissions.
+    """
+    token_file = tmp_path / "tokens.yml"
+
+    result = load_token("openai", tokens_file=token_file)
+
+    # Function should return None when creating a template
+    assert result is None
+
+    # Template file should exist
+    assert token_file.exists()
+
+    # File permissions should be user read/write only
+    assert stat.S_IMODE(token_file.stat().st_mode) == (stat.S_IRUSR | stat.S_IWUSR)
+
+    # File contents should match TOKEN_TEMPLATE
+    loaded = yaml.safe_load(token_file.read_text())
+    assert loaded == TOKEN_TEMPLATE
+
+
+def test_load_token_reads_existing(tmp_path):
+    """
+    Test that load_token returns the correct token when the token file exists.
+    """
+    token_file = tmp_path / "tokens.yml"
+    sample_tokens = {"openai": "abc123"}
+    token_file.write_text(yaml.safe_dump(sample_tokens))
+
+    result = load_token("openai", tokens_file=token_file)
+    assert result == "abc123"
+
+
+def test_load_token_missing_key(tmp_path, caplog):
+    """
+    Test that load_token returns None and logs an error when the requested
+    key is not found in the token file.
+    """
+    token_file = tmp_path / "tokens.yml"
+    token_file.write_text(yaml.safe_dump({"gemini": "xyz"}))
+
+    result = load_token("openai", tokens_file=token_file)
+
+    # Should return None for missing key
+    assert result is None
+
+    # Should log an error about missing key
+    assert "Key 'openai' not found" in caplog.text