gitai-local 1.0.0__tar.gz

gitai_local-1.0.0/LICENSE

@@ -0,0 +1,18 @@
+MIT License
+Copyright (c) 2026 GitAI
+
+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.

gitai_local-1.0.0/PKG-INFO

@@ -0,0 +1,226 @@
+Metadata-Version: 2.4
+Name: gitai-local
+Version: 1.0.0
+Summary: AI-powered conventional commit message generator running 100% locally
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/PabloSalinasDev/GitAI-CLI
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Version Control :: Git
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: llama-cpp-python[server]>=0.3.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: psutil>=6.0.0
+Requires-Dist: colorama>=0.4.6
+Dynamic: license-file
+
+# GitAI
+
+An offline, privacy-first CLI tool that automatically generates structured Git commit messages using a local LLM via `llama.cpp`. No API keys required, no data leaves your machine.
+
+<p align="center">
+  <a href="https://pypi.org/project/gitai-cli/">
+    <img src="https://img.shields.io/badge/Install-PyPI-blue?style=for-the-badge&logo=pypi" alt="Install from PyPI">
+  </a>
+  &nbsp;&nbsp;&nbsp;&nbsp;
+  <a href="https://github.com/PabloSalinasDev/GitAI-CLI/issues">
+    <img src="https://img.shields.io/badge/Report-Error-red?style=for-the-badge&logo=github" alt="Report Error">
+  </a>
+</p>
+
+---
+
+## Why GitAI? (Educational Purpose)
+
+Starting out in software development requires absorbing dozens of industry best practices simultaneously. Adopting the **Conventional Commits** standard right from the beginning often causes friction and leads to wasted time staring at a blank terminal screen wondering how to phrase a change.
+
+GitAI was built to act as an **invisible mentor inside your console**, specifically designed for developers looking to professionalize their daily workflow without losing focus on writing code.
+
+The benefit of implementing this CLI is twofold:
+
+* **Immediate Impact (Professionalism):** It resolves technical nomenclature in just a few seconds, ensuring a pristine, clean, and standardized Git history. This is ideal for making your portfolio stand out to recruiters reviewing your GitHub repositories.
+* **Passive Learning (Long-term):** It works through imitation and consistency. By interactively auditing how the AI categorizes your syntax changes with precise tags (`feat`, `fix`, `refactor`), a developer's brain naturally absorbs the pattern over time, learning how to structure correct commits organically.
+
+---
+
+## Features
+
+- **100% Local Ingestion**: Uses `llama-cpp-python` to run model inference completely offline via a background HTTP server on `localhost:8089`.
+- **Conventional Commits**: Enforces the standard `type: description` format (e.g., `feat: add user authentication`).
+- **Diff-Aware Context**: Inspects staged changes and file names to provide accurate context.
+- **Initial Commit Detection**: Automatically detects the first commit of a repository and uses the README and file list as context instead of a diff.
+- **Smart Language Memory**: Learns your language preference (English or Spanish) per repository using Git's native configuration system (`gitai.lang`), avoiding repetitive prompts.
+- **Windows & UTF-8 Native**: Fully hardened against character encoding issues (`ñ`, acentos, `¿`) when generating or editing messages in Windows consoles.
+
+## How it works
+
+1. On first use, run `gitai init` to download the AI model (~4.7 GB).
+2. At the start of each work session, run `gitai start` inside your repo. This loads the model into RAM as a background daemon and asks for your language preference if not already set.
+3. After staging changes, run `gitai`. It feeds the diff (or initial commit context) into the model and proposes a commit message.
+4. At the end of your session, run `gitai out` to stop the daemon and free RAM.
+
+---
+
+### Real-World Benchmarks & Reference Metrics
+
+![GitAI Terminal Benchmark](assets/gitai-terminal-benchmark.png)
+
+The following metrics are **estimates based on empirical testing**. Actual execution times are non-linear and may vary depending on current CPU background load...
+
+---
+
+## Project structure
+
+```
+gitai/
+├── assets/
+├── gitai/
+│   ├── __init__.py
+│   ├── config.py        ← model path, download logic, language config
+│   ├── main.py          ← CLI logic, user interaction
+│   └── llm_client.py   ← daemon management and inference via HTTP
+├── pyproject.toml       ← package definition and dependencies
+└── README.md
+```
+
+## Installation (for Python developers)
+
+First, install pipx if you don't have it:
+
+```bash
+pip install pipx
+python -m pipx ensurepath
+```
+
+> After running `ensurepath`, restart your terminal.
+
+Then install gitai globally:
+
+```bash
+pipx install --force .
+```
+
+## Setup (one time)
+
+Download the AI model (~4.7 GB). This only needs to be done once:
+
+```bash
+gitai init
+```
+
+> The model (`Qwen2.5-Coder-7B-Instruct-Q4_K_M.gguf`) is stored in `%LOCALAPPDATA%\gitai\models`.
+
+---
+
+## Usage
+
+### Start a work session
+
+Run this once per session inside your repository. Loads the model into RAM and sets the language for the repo if not already configured:
+
+```bash
+gitai start
+```
+
+### Generate a commit message
+
+```bash
+git add .
+gitai
+```
+
+### End a work session
+
+Stops the background daemon and frees RAM:
+
+```bash
+gitai out
+```
+
+---
+
+## Command reference
+
+| Command | Description |
+|---------|-------------|
+| `gitai init` | Downloads the AI model (first time only) |
+| `gitai start` | Loads the model into RAM, sets repo language |
+| `gitai` | Generates and commits staged changes |
+| `gitai out` | Stops the background daemon, frees RAM |
+
+---
+
+## Commit types used
+
+| Type | When to use |
+|------|-------------|
+| feat | New feature |
+| fix | Bug fix |
+| docs | Documentation changes |
+| style | Formatting, no logic change |
+| refactor | Code refactor |
+| test | Adding or fixing tests |
+| chore | Build, dependencies, config |
+| perf | Performance improvement |
+| ci | CI/CD changes |
+| build | Build system changes |
+
+---
+
+## Requirements
+
+- Python 3.10+
+- Git installed
+- ~4.7 GB disk space for the model
+
+## Performance & Efficiency
+
+Commit message generation runs **100% locally and entirely on your CPU**. No external APIs, no data leaks, and no heavy CUDA/ROCm GPU dependencies required. 
+
+Because inference happens directly on your processor, generation times are non-linear and scale based on your hardware architecture (specifically CPU single-core speed and RAM bandwidth), as well as the complexity of the git diff.
+
+### Real-World Benchmarks & Reference Metrics (Qwen 2.5 Coder 7B - Q4_K_M)
+
+The following metrics are **estimates based on empirical testing**. Actual execution times are non-linear and may vary depending on current CPU background load and system memory availability.
+
+Based on extensive stress-testing on standard consumer hardware (e.g., Intel i7 7th Gen with 16GB DDR4 @ 2400MHz), you can expect the following operational ranges.
+
+| Hardware Profile | Context Size | Estimated Time * | Commit Accuracy |
+|------------------|--------------|------------------|-----------------|
+| **Modern Desktop / Laptop**<br>*(Ryzen 5/7, Core i5/i7 11th+ Gen, DDR5)* | Small to Large Diffs | **~8 – 20 seconds** | ~98% |
+| **Older / Standard Hardware**<br>*(Legacy Intel i7, DDR4 @ 2400MHz)* | Small to Medium Diffs | **~20 – 40 seconds** | ~98% |
+| **Stress Test / Massive Changes**<br>*(Legacy Hardware + Dense Diffs)* | Large Multi-file Diffs | **~40 – 70 seconds** | ~98% |
+
+> **Note on Performance:** Times are heavily bound to RAM clock speed and single-core efficiency. A dense, multi-file diff analyzed on legacy hardware might occasionally touch the upper boundary of the stress test zone. However, GitAI's built-in traffic manager ensures payloads remain strictly bounded to keep local execution controlled and predictable.
+
+> **Predictable Execution Cap:** GitAI features a built-in traffic management engine. By enforcing a hard limit on filtered context sizes, the CLI prevents the LLM from entering runaway processing loops. Even during massive codebase refactors, the input payload is strictly constrained to ensure a reliable, bounded local user experience without ever freezing your terminal.
+
+### The GitAI Smart Token Optimization
+
+Why are these times so consistent? GitAI does not just dump raw data into the LLM. It includes a custom pre-processing pipeline that strips out compiler noise, binary files, white spaces, and structural brackets before sending the payload. 
+
+* **Linear vs. Deductive Processing:** Testing proved that sending a complete, clean code block up to 2500 characters is significantly faster than truncating it too early. By providing the model with full, clean context, the LLM processes the data linearly instead of wasting CPU cycles trying to "guess" missing code structures. This balance cuts down processing overhead by up to 30 seconds on older machines while boosting commit accuracy to a staggering **98%**.
+
+## Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| llama-cpp-python | Run the local AI model as an HTTP server |
+| httpx | Download the model and communicate with the daemon |
+| psutil | Stop the background daemon (`gitai out`) |
+| colorama | Handle cross-platform terminal text colorization and visual hierarchy |
+
+---
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+
+---
+
+*Developed by [Pablo Salinas](https://github.com/PabloSalinasDev)* - PyBloSoft © 2026

gitai_local-1.0.0/README.md

@@ -0,0 +1,205 @@
+# GitAI
+
+An offline, privacy-first CLI tool that automatically generates structured Git commit messages using a local LLM via `llama.cpp`. No API keys required, no data leaves your machine.
+
+<p align="center">
+  <a href="https://pypi.org/project/gitai-cli/">
+    <img src="https://img.shields.io/badge/Install-PyPI-blue?style=for-the-badge&logo=pypi" alt="Install from PyPI">
+  </a>
+  &nbsp;&nbsp;&nbsp;&nbsp;
+  <a href="https://github.com/PabloSalinasDev/GitAI-CLI/issues">
+    <img src="https://img.shields.io/badge/Report-Error-red?style=for-the-badge&logo=github" alt="Report Error">
+  </a>
+</p>
+
+---
+
+## Why GitAI? (Educational Purpose)
+
+Starting out in software development requires absorbing dozens of industry best practices simultaneously. Adopting the **Conventional Commits** standard right from the beginning often causes friction and leads to wasted time staring at a blank terminal screen wondering how to phrase a change.
+
+GitAI was built to act as an **invisible mentor inside your console**, specifically designed for developers looking to professionalize their daily workflow without losing focus on writing code.
+
+The benefit of implementing this CLI is twofold:
+
+* **Immediate Impact (Professionalism):** It resolves technical nomenclature in just a few seconds, ensuring a pristine, clean, and standardized Git history. This is ideal for making your portfolio stand out to recruiters reviewing your GitHub repositories.
+* **Passive Learning (Long-term):** It works through imitation and consistency. By interactively auditing how the AI categorizes your syntax changes with precise tags (`feat`, `fix`, `refactor`), a developer's brain naturally absorbs the pattern over time, learning how to structure correct commits organically.
+
+---
+
+## Features
+
+- **100% Local Ingestion**: Uses `llama-cpp-python` to run model inference completely offline via a background HTTP server on `localhost:8089`.
+- **Conventional Commits**: Enforces the standard `type: description` format (e.g., `feat: add user authentication`).
+- **Diff-Aware Context**: Inspects staged changes and file names to provide accurate context.
+- **Initial Commit Detection**: Automatically detects the first commit of a repository and uses the README and file list as context instead of a diff.
+- **Smart Language Memory**: Learns your language preference (English or Spanish) per repository using Git's native configuration system (`gitai.lang`), avoiding repetitive prompts.
+- **Windows & UTF-8 Native**: Fully hardened against character encoding issues (`ñ`, acentos, `¿`) when generating or editing messages in Windows consoles.
+
+## How it works
+
+1. On first use, run `gitai init` to download the AI model (~4.7 GB).
+2. At the start of each work session, run `gitai start` inside your repo. This loads the model into RAM as a background daemon and asks for your language preference if not already set.
+3. After staging changes, run `gitai`. It feeds the diff (or initial commit context) into the model and proposes a commit message.
+4. At the end of your session, run `gitai out` to stop the daemon and free RAM.
+
+---
+
+### Real-World Benchmarks & Reference Metrics
+
+![GitAI Terminal Benchmark](assets/gitai-terminal-benchmark.png)
+
+The following metrics are **estimates based on empirical testing**. Actual execution times are non-linear and may vary depending on current CPU background load...
+
+---
+
+## Project structure
+
+```
+gitai/
+├── assets/
+├── gitai/
+│   ├── __init__.py
+│   ├── config.py        ← model path, download logic, language config
+│   ├── main.py          ← CLI logic, user interaction
+│   └── llm_client.py   ← daemon management and inference via HTTP
+├── pyproject.toml       ← package definition and dependencies
+└── README.md
+```
+
+## Installation (for Python developers)
+
+First, install pipx if you don't have it:
+
+```bash
+pip install pipx
+python -m pipx ensurepath
+```
+
+> After running `ensurepath`, restart your terminal.
+
+Then install gitai globally:
+
+```bash
+pipx install --force .
+```
+
+## Setup (one time)
+
+Download the AI model (~4.7 GB). This only needs to be done once:
+
+```bash
+gitai init
+```
+
+> The model (`Qwen2.5-Coder-7B-Instruct-Q4_K_M.gguf`) is stored in `%LOCALAPPDATA%\gitai\models`.
+
+---
+
+## Usage
+
+### Start a work session
+
+Run this once per session inside your repository. Loads the model into RAM and sets the language for the repo if not already configured:
+
+```bash
+gitai start
+```
+
+### Generate a commit message
+
+```bash
+git add .
+gitai
+```
+
+### End a work session
+
+Stops the background daemon and frees RAM:
+
+```bash
+gitai out
+```
+
+---
+
+## Command reference
+
+| Command | Description |
+|---------|-------------|
+| `gitai init` | Downloads the AI model (first time only) |
+| `gitai start` | Loads the model into RAM, sets repo language |
+| `gitai` | Generates and commits staged changes |
+| `gitai out` | Stops the background daemon, frees RAM |
+
+---
+
+## Commit types used
+
+| Type | When to use |
+|------|-------------|
+| feat | New feature |
+| fix | Bug fix |
+| docs | Documentation changes |
+| style | Formatting, no logic change |
+| refactor | Code refactor |
+| test | Adding or fixing tests |
+| chore | Build, dependencies, config |
+| perf | Performance improvement |
+| ci | CI/CD changes |
+| build | Build system changes |
+
+---
+
+## Requirements
+
+- Python 3.10+
+- Git installed
+- ~4.7 GB disk space for the model
+
+## Performance & Efficiency
+
+Commit message generation runs **100% locally and entirely on your CPU**. No external APIs, no data leaks, and no heavy CUDA/ROCm GPU dependencies required. 
+
+Because inference happens directly on your processor, generation times are non-linear and scale based on your hardware architecture (specifically CPU single-core speed and RAM bandwidth), as well as the complexity of the git diff.
+
+### Real-World Benchmarks & Reference Metrics (Qwen 2.5 Coder 7B - Q4_K_M)
+
+The following metrics are **estimates based on empirical testing**. Actual execution times are non-linear and may vary depending on current CPU background load and system memory availability.
+
+Based on extensive stress-testing on standard consumer hardware (e.g., Intel i7 7th Gen with 16GB DDR4 @ 2400MHz), you can expect the following operational ranges.
+
+| Hardware Profile | Context Size | Estimated Time * | Commit Accuracy |
+|------------------|--------------|------------------|-----------------|
+| **Modern Desktop / Laptop**<br>*(Ryzen 5/7, Core i5/i7 11th+ Gen, DDR5)* | Small to Large Diffs | **~8 – 20 seconds** | ~98% |
+| **Older / Standard Hardware**<br>*(Legacy Intel i7, DDR4 @ 2400MHz)* | Small to Medium Diffs | **~20 – 40 seconds** | ~98% |
+| **Stress Test / Massive Changes**<br>*(Legacy Hardware + Dense Diffs)* | Large Multi-file Diffs | **~40 – 70 seconds** | ~98% |
+
+> **Note on Performance:** Times are heavily bound to RAM clock speed and single-core efficiency. A dense, multi-file diff analyzed on legacy hardware might occasionally touch the upper boundary of the stress test zone. However, GitAI's built-in traffic manager ensures payloads remain strictly bounded to keep local execution controlled and predictable.
+
+> **Predictable Execution Cap:** GitAI features a built-in traffic management engine. By enforcing a hard limit on filtered context sizes, the CLI prevents the LLM from entering runaway processing loops. Even during massive codebase refactors, the input payload is strictly constrained to ensure a reliable, bounded local user experience without ever freezing your terminal.
+
+### The GitAI Smart Token Optimization
+
+Why are these times so consistent? GitAI does not just dump raw data into the LLM. It includes a custom pre-processing pipeline that strips out compiler noise, binary files, white spaces, and structural brackets before sending the payload. 
+
+* **Linear vs. Deductive Processing:** Testing proved that sending a complete, clean code block up to 2500 characters is significantly faster than truncating it too early. By providing the model with full, clean context, the LLM processes the data linearly instead of wasting CPU cycles trying to "guess" missing code structures. This balance cuts down processing overhead by up to 30 seconds on older machines while boosting commit accuracy to a staggering **98%**.
+
+## Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| llama-cpp-python | Run the local AI model as an HTTP server |
+| httpx | Download the model and communicate with the daemon |
+| psutil | Stop the background daemon (`gitai out`) |
+| colorama | Handle cross-platform terminal text colorization and visual hierarchy |
+
+---
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+
+---
+
+*Developed by [Pablo Salinas](https://github.com/PabloSalinasDev)* - PyBloSoft © 2026

gitai_local-1.0.0/gitai/config.py

@@ -0,0 +1,129 @@
+import os
+import threading
+import time
+import sys
+import subprocess
+from pathlib import Path
+from colorama import init, Fore, Style
+
+init(autoreset=True)
+
+
+MODEL_DIR      = Path(os.environ.get("LOCALAPPDATA", ".")) / "gitai" / "models"
+MODEL_FILENAME = "Qwen2.5.1-Coder-7B-Instruct-Q4_K_M.gguf"
+MODEL_PATH     = MODEL_DIR / MODEL_FILENAME
+MODEL_URL      = "https://huggingface.co/bartowski/Qwen2.5.1-Coder-7B-Instruct-GGUF/resolve/main/Qwen2.5.1-Coder-7B-Instruct-Q4_K_M.gguf?download=true"
+PORT           = 8089
+
+def get_secure_env():
+    env = os.environ.copy()
+    env["LC_ALL"] = "C.UTF-8"
+    env["LANG"] = "C.UTF-8"
+    return env
+
+def model_exists():
+    return MODEL_PATH.exists() and MODEL_PATH.stat().st_size > 100_000_000
+
+def download_model(on_progress, on_done, on_error):
+    import httpx
+    def run():
+        try:
+            MODEL_DIR.mkdir(parents=True, exist_ok=True)
+            tmp_path = MODEL_PATH.with_suffix(".tmp")
+
+            with httpx.stream("GET", MODEL_URL, follow_redirects=True, timeout=None) as r:
+                r.raise_for_status()
+                total      = int(r.headers.get("content-length", 0))
+                downloaded = 0
+
+                with open(tmp_path, "wb") as f:
+                    for chunk in r.iter_bytes(chunk_size=1024 * 256):
+                        f.write(chunk)
+                        downloaded += len(chunk)
+                        if total:
+                            pct  = downloaded / total
+                            d_gb = downloaded / 1_073_741_824
+                            t_gb = total      / 1_073_741_824
+                            on_progress(pct, d_gb, t_gb)
+
+            tmp_path.rename(MODEL_PATH)
+            on_done()
+
+        except Exception as e:
+            on_error(str(e))
+
+    threading.Thread(target=run, daemon=True).start()
+
+def ensure_model():
+    if model_exists():
+        return
+
+    print(Fore.CYAN + "┌─────────────────────────────────────────────┐")
+    print(Fore.CYAN + "│   GitAI - First run: downloading AI model   │")
+    print(Fore.CYAN + "│       AI Model Setup - one time only        │")
+    print(Fore.CYAN + "└─────────────────────────────────────────────┘\n")
+
+    done_flag = {"done": False, "error": None}
+
+    def on_progress(pct, d_gb, t_gb):
+        bar_len = 30
+        filled  = int(bar_len * pct)
+        bar     = Fore.YELLOW + "█" * filled + Style.DIM + "░" * (bar_len - filled)
+        print(Fore.YELLOW + f"\r  [{bar}" + Style.RESET_ALL + Fore.YELLOW + f"] {pct*100:.1f}%  {d_gb:.2f}/{t_gb:.2f} GB", end="", flush=True)
+
+    def on_done():
+        done_flag["done"] = True
+
+    def on_error(e):
+        done_flag["error"] = e
+
+    download_model(on_progress, on_done, on_error)
+
+    while not done_flag["done"] and not done_flag["error"]:
+        time.sleep(0.5)
+
+    if done_flag["error"]:
+        print(Fore.RED + f"\n\n Error downloading model: {done_flag['error']}")
+        sys.exit(1)
+
+    print(Fore.GREEN + "\n\n Model downloaded successfully.\n")
+
+def get_repo_language(force_ask=False):
+    """
+    Checks if the language configuration exists for this repository.
+    If it doesn't exist or force_ask is True, it asks the user and saves it.
+    """
+    if not force_ask:
+        result = subprocess.run(
+            ["git", "config", "--get", "gitai.lang"],
+            capture_output=True,
+            text=True,
+            check=False,
+            encoding="utf-8",
+            errors="replace",
+            env=get_secure_env()
+        )
+        stored_lang = result.stdout.strip().lower()
+        if stored_lang in ["es", "en"]:
+            return stored_lang
+
+    print(Fore.CYAN + "\n  [gitai] Language configuration for this repository:")
+    while True:
+        choice = input(Fore.CYAN + "  [s] Spanish  [e] English  → ").strip().lower()
+        if choice == "s":
+            lang = "es"
+            break
+        elif choice == "e":
+            lang = "en"
+            break
+        else:
+            print(Fore.RED + "  Invalid option. Please select 's' or 'e'.")
+
+    subprocess.run(
+        ["git", "config", "gitai.lang", lang],
+        encoding="utf-8",
+        check=False,
+        env=get_secure_env()
+    )
+    print(Fore.GREEN + f" Language saved as '{lang}' in the Git configuration of this project.\n")
+    return lang