git-cai-cli 0.16.2__tar.gz → 0.17.1__tar.gz

{git_cai_cli-0.16.2 → git_cai_cli-0.17.1}/.linters/lychee.toml

@@ -8,7 +8,10 @@ accept = ["200", "429"]
 
 exclude = [
     "https://megalinter.io/configuration/",
-    "file:///tmp/lint/dwh/models/logo.png"
+    "file:///tmp/lint/dwh/models/logo.png",
+    # Example endpoints in the custom provider docs, not browsable pages.
+    "^http://localhost",
+    "^https://openrouter\\.ai/api/v1$",
     ]
 
 exclude_path = [

{git_cai_cli-0.16.2 → git_cai_cli-0.17.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: git-cai-cli
-Version: 0.16.2
+Version: 0.17.1
 Summary: Use LLM to create git commit messages
 Author-email: Thorsten Foltz <thorsten.foltz@live.com>
 License-Expression: MIT
@@ -49,6 +49,7 @@ Currently supported providers:
 - Mistral
 - DeepSeek
 - Ollama (local)
+- Any OpenAI compatible API (OpenRouter, Together, Cerebras, LM Studio, vLLM, llama.cpp, LiteLLM, ...) via `base_url`
 
 ---
 
@@ -58,6 +59,7 @@ Currently supported providers:
 - [pipx](https://pypi.org/project/pipx/)
 - Either:
   - Ollama installed and running locally, or
+  - A local OpenAI compatible server such as LM Studio or vLLM, or
   - An API key for at least one of the following providers:
   - OpenAI
   - Gemini (free tier available)
@@ -74,7 +76,7 @@ Currently supported providers:
 - Automatically detects added, modified, and deleted files
 - Generates meaningful, context-aware commit messages using an LLM
 - Seamless integration with Git
-- Supports multiple LLM providers and models
+- Supports multiple LLM providers and models, plus any OpenAI compatible endpoint
 - Global configuration with per-repository overrides
 - Interactive `--init` wizard for first-time setup (provider, token, language, style)
 - Repository-specific language, style, and model selection
@@ -93,7 +95,7 @@ Currently supported providers:
 - Optional large-diff guard (`max_diff_bytes`) that truncates oversized diffs before sending
 - Generation time measurement
 - Local-only usage analytics (per-provider commits, tokens, latency) with opt-in SQLite storage
-- Shell completion for bash, zsh, and fish
+- Shell completion for bash, zsh, and fish (including custom providers from your config)
 - Local secret scan that blocks the diff before it reaches the provider when likely credentials are detected
 - Configuration doctor (`--check`) that validates your setup offline, with an optional live provider probe (`--ping`)
 - Mixed code and documentation diffs are classified by the functional change rather than mislabelled as docs
@@ -188,6 +190,27 @@ Set your preferred LLM in `cai_config.yml` (Groq by default).
 
 If you want to use Ollama, install it, set `default: ollama` and configure the `ollama:` block (model/temperature). Ollama is automatically started when used.
 
+### Custom OpenAI compatible providers
+
+Any service speaking the OpenAI `/chat/completions` API can be added as a provider.
+Pick a name, add a block with `base_url` and `model`, and set `default:` to that name:
+
+```yaml
+default: openrouter
+openrouter:
+  base_url: https://openrouter.ai/api/v1
+  model: meta-llama/llama-3.3-70b-instruct:free
+lmstudio:
+  base_url: http://localhost:1234/v1
+  model: qwen2.5-coder
+  requires_token: false
+```
+
+The API key goes into `tokens.yml` under the same name (`openrouter: sk-or-...`).
+With `requires_token: false` no key is needed. `/chat/completions` is appended to
+`base_url` unless it is already there. The name works with `-P` / `--provider`
+and shows up in `git cai -l provider` and shell completion.
+
 ### Custom prompts (Markdown)
 
 The generated commit message is guided by prompt files.
@@ -247,6 +270,10 @@ git cai -g
 - `style` – tone or style of the commit message
 - `emoji` – enable or disable emojis
 - `load_tokens_from` – path to the file where API tokens are stored
+- `base_url` – per provider block: endpoint of a custom OpenAI compatible provider, or a proxy/gateway for a built in one.
+OpenAI style providers include the version (`https://gateway.example/v1`); `anthropic` and `gemini` take the host without it (`https://gateway.example`)
+- `requires_token` – per provider block: set to `false` for custom providers that need no API key; default `true`
+- `max_output_tokens` – per provider block: cap on the reply length for Anthropic and OpenAI compatible providers; only sent when set
 - `prompt_file` - path to the file where the prompt for the commit is stored
 - `squash_prompt_file` - path to the file where the prompt for the squash is stored
 - `full_files_prompt_file` - path to the prompt used when `-F` / `--full-files` attaches full file contents
@@ -264,7 +291,8 @@ git cai -g
 No diff content, commit messages, or file paths are stored — only metadata (provider, model, kind, repo name, token counts, latency, settings)
 - `signoff` – append a `Signed-off-by:` trailer (built from git `user.name` / `user.email`) to every commit message; default `false`
 - `secret_scan` – scan the outgoing diff for likely secrets and ask before sending; default `true`. Bypass once with `-B` / `--allow-secrets`,
-or disable entirely by setting it to `false`. Skipped for tokenless providers (Ollama), where nothing leaves the machine
+or disable entirely by setting it to `false`. Skipped for tokenless providers (Ollama), where nothing leaves the machine.
+Custom providers are always scanned, even with `requires_token: false`, since the diff may leave the machine
 
 ---
 
@@ -286,13 +314,13 @@ In addition to `git cai`, the following options are available:
 - `-H`, `--set-home` – set a config value in home config (`key=value`), always targets `~/.config/cai/`
 - `-h`, `--help` – show help and available commands
 - `-I`, `--init` – interactive setup wizard (writes home config and tokens.yml)
-- `-i`, `--install-completion` – install shell completion for bash, zsh, or fish
+- `-i`, `--install-completion` – install shell completion for bash, zsh, or fish. Rerun after upgrading to get custom provider completion
 - `-k`, `--check` – run configuration diagnostics offline (config source, provider, token, prompts, editor, style)
 - `-l`, `--list` – list available information. Valid types: `config`, `editor`, `language`, `model`, `path`, `provider`, `style`
 - `-m`, `--model` – override the model for this invocation (requires `-P`)
 - `-n`, `--ping` – with `--check`, also send a tiny request to the active provider to confirm reachability
 - `-o`, `--signoff` / `--no-signoff` – append a `Signed-off-by:` trailer (uses git `user.name` / `user.email`); applies to commit, amend, and squash modes
-- `-P`, `--provider` – override the LLM provider for this invocation
+- `-P`, `--provider` – override the LLM provider for this invocation (built in or custom; tab completion lists both)
 - `-p`, `--generate-prompts` – generate default `commit_prompt.md` and `squash_prompt.md` in the current directory (for customization)
 - `--print` – print the generated commit message to stdout and exit without committing (commit/amend modes only; mutually exclusive with `-c`)
 - `-q`, `--sql true|false` – override stats writing for this run (wins over the persisted `stats` config)
@@ -511,7 +539,8 @@ git cai -S secret_scan=false     # disable the scan persistently
 
 Obvious placeholders (`example`, `dummy`, repeated filler, and similar) are
 ignored to keep the noise down, and the scan is skipped entirely for tokenless
-providers such as Ollama, where nothing leaves the machine. In non-interactive
+providers such as Ollama, where nothing leaves the machine. Custom providers are
+always scanned, even with `requires_token: false`. In non-interactive
 runs (`-c` / `--crazy`, or no TTY) a detection aborts the send instead of
 prompting; re-run with `-B` to override.
 

{git_cai_cli-0.16.2 → git_cai_cli-0.17.1}/README.md

@@ -20,6 +20,7 @@ Currently supported providers:
 - Mistral
 - DeepSeek
 - Ollama (local)
+- Any OpenAI compatible API (OpenRouter, Together, Cerebras, LM Studio, vLLM, llama.cpp, LiteLLM, ...) via `base_url`
 
 ---
 
@@ -29,6 +30,7 @@ Currently supported providers:
 - [pipx](https://pypi.org/project/pipx/)
 - Either:
   - Ollama installed and running locally, or
+  - A local OpenAI compatible server such as LM Studio or vLLM, or
   - An API key for at least one of the following providers:
   - OpenAI
   - Gemini (free tier available)
@@ -45,7 +47,7 @@ Currently supported providers:
 - Automatically detects added, modified, and deleted files
 - Generates meaningful, context-aware commit messages using an LLM
 - Seamless integration with Git
-- Supports multiple LLM providers and models
+- Supports multiple LLM providers and models, plus any OpenAI compatible endpoint
 - Global configuration with per-repository overrides
 - Interactive `--init` wizard for first-time setup (provider, token, language, style)
 - Repository-specific language, style, and model selection
@@ -64,7 +66,7 @@ Currently supported providers:
 - Optional large-diff guard (`max_diff_bytes`) that truncates oversized diffs before sending
 - Generation time measurement
 - Local-only usage analytics (per-provider commits, tokens, latency) with opt-in SQLite storage
-- Shell completion for bash, zsh, and fish
+- Shell completion for bash, zsh, and fish (including custom providers from your config)
 - Local secret scan that blocks the diff before it reaches the provider when likely credentials are detected
 - Configuration doctor (`--check`) that validates your setup offline, with an optional live provider probe (`--ping`)
 - Mixed code and documentation diffs are classified by the functional change rather than mislabelled as docs
@@ -159,6 +161,27 @@ Set your preferred LLM in `cai_config.yml` (Groq by default).
 
 If you want to use Ollama, install it, set `default: ollama` and configure the `ollama:` block (model/temperature). Ollama is automatically started when used.
 
+### Custom OpenAI compatible providers
+
+Any service speaking the OpenAI `/chat/completions` API can be added as a provider.
+Pick a name, add a block with `base_url` and `model`, and set `default:` to that name:
+
+```yaml
+default: openrouter
+openrouter:
+  base_url: https://openrouter.ai/api/v1
+  model: meta-llama/llama-3.3-70b-instruct:free
+lmstudio:
+  base_url: http://localhost:1234/v1
+  model: qwen2.5-coder
+  requires_token: false
+```
+
+The API key goes into `tokens.yml` under the same name (`openrouter: sk-or-...`).
+With `requires_token: false` no key is needed. `/chat/completions` is appended to
+`base_url` unless it is already there. The name works with `-P` / `--provider`
+and shows up in `git cai -l provider` and shell completion.
+
 ### Custom prompts (Markdown)
 
 The generated commit message is guided by prompt files.
@@ -218,6 +241,10 @@ git cai -g
 - `style` – tone or style of the commit message
 - `emoji` – enable or disable emojis
 - `load_tokens_from` – path to the file where API tokens are stored
+- `base_url` – per provider block: endpoint of a custom OpenAI compatible provider, or a proxy/gateway for a built in one.
+OpenAI style providers include the version (`https://gateway.example/v1`); `anthropic` and `gemini` take the host without it (`https://gateway.example`)
+- `requires_token` – per provider block: set to `false` for custom providers that need no API key; default `true`
+- `max_output_tokens` – per provider block: cap on the reply length for Anthropic and OpenAI compatible providers; only sent when set
 - `prompt_file` - path to the file where the prompt for the commit is stored
 - `squash_prompt_file` - path to the file where the prompt for the squash is stored
 - `full_files_prompt_file` - path to the prompt used when `-F` / `--full-files` attaches full file contents
@@ -235,7 +262,8 @@ git cai -g
 No diff content, commit messages, or file paths are stored — only metadata (provider, model, kind, repo name, token counts, latency, settings)
 - `signoff` – append a `Signed-off-by:` trailer (built from git `user.name` / `user.email`) to every commit message; default `false`
 - `secret_scan` – scan the outgoing diff for likely secrets and ask before sending; default `true`. Bypass once with `-B` / `--allow-secrets`,
-or disable entirely by setting it to `false`. Skipped for tokenless providers (Ollama), where nothing leaves the machine
+or disable entirely by setting it to `false`. Skipped for tokenless providers (Ollama), where nothing leaves the machine.
+Custom providers are always scanned, even with `requires_token: false`, since the diff may leave the machine
 
 ---
 
@@ -257,13 +285,13 @@ In addition to `git cai`, the following options are available:
 - `-H`, `--set-home` – set a config value in home config (`key=value`), always targets `~/.config/cai/`
 - `-h`, `--help` – show help and available commands
 - `-I`, `--init` – interactive setup wizard (writes home config and tokens.yml)
-- `-i`, `--install-completion` – install shell completion for bash, zsh, or fish
+- `-i`, `--install-completion` – install shell completion for bash, zsh, or fish. Rerun after upgrading to get custom provider completion
 - `-k`, `--check` – run configuration diagnostics offline (config source, provider, token, prompts, editor, style)
 - `-l`, `--list` – list available information. Valid types: `config`, `editor`, `language`, `model`, `path`, `provider`, `style`
 - `-m`, `--model` – override the model for this invocation (requires `-P`)
 - `-n`, `--ping` – with `--check`, also send a tiny request to the active provider to confirm reachability
 - `-o`, `--signoff` / `--no-signoff` – append a `Signed-off-by:` trailer (uses git `user.name` / `user.email`); applies to commit, amend, and squash modes
-- `-P`, `--provider` – override the LLM provider for this invocation
+- `-P`, `--provider` – override the LLM provider for this invocation (built in or custom; tab completion lists both)
 - `-p`, `--generate-prompts` – generate default `commit_prompt.md` and `squash_prompt.md` in the current directory (for customization)
 - `--print` – print the generated commit message to stdout and exit without committing (commit/amend modes only; mutually exclusive with `-c`)
 - `-q`, `--sql true|false` – override stats writing for this run (wins over the persisted `stats` config)
@@ -482,7 +510,8 @@ git cai -S secret_scan=false     # disable the scan persistently
 
 Obvious placeholders (`example`, `dummy`, repeated filler, and similar) are
 ignored to keep the noise down, and the scan is skipped entirely for tokenless
-providers such as Ollama, where nothing leaves the machine. In non-interactive
+providers such as Ollama, where nothing leaves the machine. Custom providers are
+always scanned, even with `requires_token: false`. In non-interactive
 runs (`-c` / `--crazy`, or no TTY) a detection aborts the send instead of
 prompting; re-run with `-B` to override.
 

{git_cai_cli-0.16.2 → git_cai_cli-0.17.1}/docs/git-cai.txt

@@ -73,7 +73,8 @@ First run / configuration (manual):
 - Add at least one API key to `~/.config/cai/tokens.yml` (created as a template if missing).
   The YAML keys are provider names (for example: `openai`, `anthropic`, `gemini`,
   `groq`, `xai`, `mistral`, `deepseek`).
-  If you use `ollama` as provider, no token is required.
+  If you use `ollama` as provider, no token is required. Custom providers use
+  their own name as key (see below).
 - In `~/.config/cai/cai_config.yml`, set `default:` to the provider you want and
   adjust the provider block (model/temperature) as needed.
 
@@ -89,6 +90,46 @@ Custom prompts (optional):
 - Generate prompt files in the current directory with `git cai -p`.
 - Point `prompt_file` / `squash_prompt_file` in `cai_config.yml` to your custom files.
 
+Custom OpenAI compatible providers (optional):
+
+- Any service speaking the OpenAI `/chat/completions` API (OpenRouter, Together,
+  Cerebras, GitHub Models, LiteLLM, vLLM, LM Studio, llama.cpp, ...) can be added
+  as a provider. Pick a name, add a block with `base_url` and `model`, and set
+  `default:` to that name:
+
+    default: openrouter
+    openrouter:
+      base_url: https://openrouter.ai/api/v1
+      model: meta-llama/llama-3.3-70b-instruct:free
+      temperature: 0        # optional
+      timeout: 60           # optional
+      max_output_tokens: 2048 # optional, cap on the reply length
+    lmstudio:
+      base_url: http://localhost:1234/v1
+      model: qwen2.5-coder
+      requires_token: false # optional, default true
+
+- `/chat/completions` is appended to `base_url` unless it is already there.
+- The API key goes into `~/.config/cai/tokens.yml` under the same name
+  (`openrouter: sk-or-...`). With `requires_token: false` no key is needed and
+  no `Authorization` header is sent.
+- The name works with `--provider` (`git cai -P lmstudio`), is listed by
+  `git cai -l provider`, and is offered by shell completion.
+- `max_output_tokens` is only sent when set. Useful for local servers whose
+  default reply limit truncates commit messages. It is sent as `max_tokens`,
+  or as `max_completion_tokens` for the `openai` block.
+- `base_url` also works in the built in blocks to route them through a proxy or
+  gateway. Use the same form as the vendor SDKs:
+  `openai`, `deepseek`, `groq`, `mistral`, `xai`: include the version,
+  e.g. `https://gateway.example/v1` (`/chat/completions` is appended);
+  `anthropic`: without version, e.g. `https://gateway.example`
+  (`/v1/messages` is appended);
+  `gemini`: without version, e.g. `https://gateway.example`
+  (`/v1beta/models/<model>:generateContent` is appended).
+  `ollama` keeps using the `OLLAMA_HOST` environment variable.
+- The secret scan stays active for custom providers, including local ones.
+  Set `secret_scan: false` to disable it.
+
 OPTIONS
 -------
 -A, --amend::
@@ -283,7 +324,8 @@ Useful when a working tree contains unrelated staged changes and the commit
 should focus on a subset of them, or when you want the LLM to concentrate
 on a specific file.
 +
-Cannot be used with `--list`, `--update`, or `--squash`.
+Only valid in the default commit mode; cannot be used with `--amend`,
+`--list`, `--update`, or `--squash`.
 +
 ----
 git cai -f src/foo.py
@@ -349,7 +391,10 @@ git cai -I
 
 -i, --install-completion::
 Install shell completion for `git cai`. Supports bash, zsh, and fish.
-Completions cover all flags and provider names for `--provider`.
+Completions cover all flags and provider names for `--provider`, including
+custom providers from the active config (looked up on each TAB press, so new
+providers show up without reinstalling). Users of an older script need to run
+`git cai -i` once more to get this.
 +
 After installation, restart your terminal or source your shell configuration
 file for the completions to take effect.
@@ -361,8 +406,9 @@ git cai -i
 -k, --check::
 Run configuration diagnostics and exit. The check is offline by default: it
 reports which config is authoritative (repository, home, or built-in), validates
-the config keys, confirms the default provider has a model and a
-usable token, that the commit/squash/full-files/PR prompts resolve, and that the
+the config keys, confirms the default provider has a model (and shows its
+`base_url` if set) and a usable token (skipped for `ollama` and providers with
+`requires_token: false`), that the commit/squash/full-files/PR prompts resolve, and that the
 configured editor is on `PATH`. Exits non-zero if any check fails. Add `--ping`
 to also probe the active provider with a tiny live request.
 +
@@ -476,11 +522,14 @@ git cai -s --signoff
 Override the LLM provider for this invocation. The model and temperature
 from the configuration for that provider are used unless `--model` is also
 specified. Available providers: `anthropic`, `deepseek`, `gemini`, `groq`,
-`mistral`, `ollama`, `openai`, `xai`.
+`mistral`, `ollama`, `openai`, `xai`, plus any custom OpenAI compatible
+provider defined in the active config (see SETUP). Shell completion offers
+both.
 +
 ----
 git cai -P anthropic
 git cai -P groq -m llama-3.3-70b
+git cai -P openrouter
 ----
 
 -p, --generate-prompts::
@@ -941,7 +990,9 @@ Configuration file paths:
 provider::
 List all supported LLM providers. Each provider is shown with its default
 model and whether an API token is required. Providers that do not require a
-token (currently only `ollama`) are marked accordingly.
+token (`ollama`, and custom providers with `requires_token: false`) are
+marked accordingly. Custom OpenAI compatible providers from the active config
+follow in a separate section with their `base_url`.
 +
 ----
 git cai -l provider
@@ -960,6 +1011,11 @@ Supported providers:
   ollama       model: llama3.1                           (no token required)
   openai       model: gpt-5.4-mini                       (token required)
   xai          model: grok-4.3                           (token required)
+
+Custom providers (OpenAI compatible, from config):
+
+  lmstudio     model: qwen2.5-coder                       (no token required) http://localhost:1234/v1
+  openrouter   model: meta-llama/llama-3.3-70b-instruct:free (token required) https://openrouter.ai/api/v1
 ----
 
 style::
@@ -1019,7 +1075,8 @@ Available configuration keys:
   credential formats are flagged (private keys, AWS/GitHub/Slack/Google/OpenAI
   keys); obvious placeholders (values containing `example`, `sample`, `dummy`,
   and repeated-character filler) are ignored. Local providers (Ollama) skip the
-  scan, since nothing leaves the machine. When you confirm a flagged send in an
+  scan, since nothing leaves the machine. Custom providers are always scanned,
+  even with `requires_token: false`, since the diff may leave the machine. When you confirm a flagged send in an
   interactive commit (a false alarm), git-cai offers, per flagged file, to
   remember the decision: add the file to `.caiignore` (drop it from git-cai
   entirely), add it to `secret_scan_exclude` (keep sending it but skip its
@@ -1073,10 +1130,18 @@ Available configuration keys:
   the middle step).
 - `<provider>.model` -- model name for a specific provider
 - `<provider>.temperature` -- temperature for a specific provider
-- `anthropic.max_tokens` -- upper bound on Anthropic response tokens
-  (default `32768`)
-- `ollama.timeout` -- HTTP timeout in seconds for Ollama generation calls
-  (default `300`; overrides the global `timeout` for this provider only)
+- `<provider>.base_url` -- endpoint of a custom OpenAI compatible provider,
+  or a proxy/gateway for a built in one. OpenAI style providers include the
+  version (`https://gateway.example/v1`); `anthropic` and `gemini` take the
+  host without it (`https://gateway.example`). Must be an http(s) URL. Not
+  used by `ollama` (use `OLLAMA_HOST`).
+- `<provider>.requires_token` -- set to `false` for a custom provider that
+  needs no API key; no `Authorization` header is sent (default `true`)
+- `<provider>.max_output_tokens` -- upper bound on response tokens. For
+  `anthropic` the default is `32768` (`max_tokens` is still read as a legacy
+  alias). For OpenAI compatible providers it is only sent when set.
+- `<provider>.timeout` -- HTTP timeout in seconds for one provider,
+  overriding the global `timeout` (`ollama` defaults to `300`)
 - `stats` -- opt in to local-only usage analytics (`true`/`false`,
   default `false`). When enabled, every generation appends one row to
   `~/.local/share/git-cai/stats.db` capturing kind (`commit`, `amend`,
@@ -1234,6 +1299,12 @@ Override the provider for a single invocation:
 git cai -P anthropic
 ----
 
+Use a custom OpenAI compatible provider defined in the config:
+
+----
+git cai -P lmstudio
+----
+
 Override both provider and model:
 
 ----