Metadata-Version: 2.4
Name: gitaiflow
Version: 1.0.5
Summary: Provider-agnostic AI change-summary generator for git repos -- works with Gemini, OpenAI, or local Ollama models.
Author: CodeFleet Labs
License-Expression: MIT
Project-URL: Homepage, https://gitlab.com/codefleet-labs/gitaiflow
Project-URL: Repository, https://gitlab.com/codefleet-labs/gitaiflow
Project-URL: Issues, https://gitlab.com/codefleet-labs/gitaiflow/-/issues
Keywords: gitaiflow,ai,git,diff,engineering,django,ollama,llm,pr-summary,developer-tools,git-analysis
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Topic :: Utilities
Classifier: Environment :: Console
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27.0
Provides-Extra: dev
Requires-Dist: ruff>=0.5.0; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: build>=1.2.1; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"
Dynamic: license-file

# gitaiflow

**AI-assisted Git change summarization and engineering analysis for Python developers.**

<u>Maintained by: <a href="https://djangoplay.org"></a> https://djangoplay.org</u>

`gitaiflow` analyzes your Git changes with an AI model and produces a structured, timestamped change summary that can be used as a commit title/body, piped into Git workflows, or consumed by another tool or agent.

It is **provider-agnostic**: use Google Gemini, a local Ollama model, or any OpenAI-compatible endpoint such as OpenAI, Groq, DeepSeek, OpenRouter, vLLM, or LM Studio.

## Features

* Generate AI summaries from Git diffs
* Summarize a directory or individual file
* Generate commit-ready titles and bodies
* Produce structured JSON output
* Optionally generate a Markdown representation
* Print commit messages directly to stdout
* Skip selected paths such as migrations or tests
* Compare against a specified remote and base branch
* Use cloud or fully local AI models
* Query OpenRouter's live model catalog
* No vendor lock-in

## Requirements

* Python 3.11 or later
* Git
* An AI provider configured before running `gitaiflow`

## Installation

```bash
pip install gitaiflow
```

## Quick Start

Configure an AI provider and run:

```bash
gitaiflow --path .
```

For a commit-ready message:

```bash
gitaiflow --path . --print-commit
```

Example:

```text
mailer: add retry backoff for failed sends

- Added exponential backoff retry logic in retry.py
- tasks.py now retries send_mail up to 3 times on failure
- No changes to public function signatures
```

The commit output can be piped directly into Git:

```bash
gitaiflow --path . --print-commit > /tmp/msg.txt
git commit -F /tmp/msg.txt
```

## AI Provider Configuration

`gitaiflow` requires an AI model. It supports Gemini, Ollama, and OpenAI-compatible endpoints.

Configuration can be provided through real environment variables or a `.env` file. A real environment variable always wins over `.env`. gitaiflow finds `.env` by searching from the current directory up to the repository root, so it works no matter which subdirectory you run it from.

### OpenRouter

OpenRouter can be used with its free model router or with a specific model available through your account.

```bash
AI_PROVIDER=custom
AI_BASE_URL=https://openrouter.ai/api/v1
AI_API_KEY=<your-openrouter-api-key>
AI_MODEL=openrouter/free

AI_TEMPERATURE=0.2
AI_MAX_TOKENS=10000
AI_REQUEST_TIMEOUT=60
```

Keep API keys private and never commit `.env` to source control.

To list currently available free OpenRouter models:

```bash
gitaiflow --list-models --free-only
```

To list the full OpenRouter catalog:

```bash
gitaiflow --list-models
```

Add `--json` when you need the raw model metadata.

### Google Gemini

```bash
export AI_PROVIDER=gemini
export AI_API_KEY=<your-key>
```

### Ollama

For fully local inference:

```bash
export AI_PROVIDER=ollama
export AI_MODEL=llama3.2:3b
```

The model name must match a model available from your local Ollama installation.

### OpenAI-Compatible Providers

```bash
export AI_PROVIDER=custom
export AI_BASE_URL=<endpoint>
export AI_API_KEY=<key>
export AI_MODEL=<model>
```

This can be used with OpenAI-compatible services including OpenAI, Groq, DeepSeek, OpenRouter, vLLM, LM Studio, and other compatible endpoints.

## Configuration

| Variable             | Default          | Description                                   |
| -------------------- | ---------------- | --------------------------------------------- |
| `AI_PROVIDER`        | `gemini`         | `gemini`, `ollama`, `openai`, or `custom`     |
| `AI_BASE_URL`        | Provider default | Optional API endpoint override                |
| `AI_API_KEY`         | None             | API key for cloud/OpenAI-compatible providers |
| `AI_MODEL`           | Provider default | Model identifier                              |
| `AI_TEMPERATURE`     | `0.2`            | Model temperature                             |
| `AI_MAX_TOKENS`      | `10000`          | Maximum generated tokens                      |
| `AI_REQUEST_TIMEOUT` | `60`             | Request timeout in seconds                    |

## Usage

Summarize a directory:

```bash
gitaiflow --path mailer/
```

Summarize a single file:

```bash
gitaiflow --path users/views/logout.py
```

Skip paths:

```bash
gitaiflow --path . --skip migrations tests
```

Use a specific remote and base branch:

```bash
gitaiflow --path . --remote upstream --base-branch develop
```

Write output to a custom location:

```bash
gitaiflow --path . -o artifacts/
```

Generate a Markdown representation in addition to JSON:

```bash
gitaiflow --path . --markdown
```

Print a commit-ready title and body:

```bash
gitaiflow --path . --print-commit
```

## Output

Each run produces a structured JSON change summary, written to
`change-summary/<YYYY>/<MM>/<DD>/json/<target>-<timestamp>.json`
(partitioned by the date of the run), containing Git-derived information
such as:

* Repository and branch
* Target and target type
* Base revision
* Change window
* Changed files and statuses
* AI provider and model
* Generated commit title
* Generated commit body

The generated commit title and body are the model-generated portions of the result. Git metadata such as the branch, base, changed files, and change window comes directly from Git.

With `--markdown`, `gitaiflow` also produces a human-readable Markdown representation from the same JSON data.

## Local Usage Tracking

`gitaiflow` maintains a local usage log at:

```text
~/.gitaiflow/usage.jsonl
```

The log records local execution information such as timestamps, repository name, model used, estimated token counts, duration, and success status.

The usage log remains on the user's machine.

Optional local daily limits can be configured with:

```bash
export GITAIFLOW_MAX_RUNS_PER_DAY=20
export GITAIFLOW_MAX_TOKENS_PER_DAY=50000
```

These are local courtesy limits, not server-side quotas or enforcement.

## Privacy and Telemetry

`gitaiflow` does **not** phone home by default. The first time telemetry status matters and you're at an interactive terminal, it asks:

```text
Enable anonymous usage telemetry? [y/N]
```

The consent notice (exactly what's collected, and what never is) is printed before that question, not after -- so you decide with the facts in front of you, not after the fact. A bare Enter, Ctrl-C, or EOF is treated as **no**, not a dismissible nag.

Your answer is saved locally so you're only asked once per machine. It's kept separate from the local usage log below, so clearing that log doesn't also reset your telemetry decision -- you'd otherwise be asked again on the next run. You can change it anytime with:

```bash
export GITAIFLOW_TELEMETRY=true   # or false
```

which always overrides the saved answer (and the prompt) -- useful for CI, where `gitaiflow` never prompts (no interactive terminal) and defaults to off unless this is set.

### Durable consent

`GITAIFLOW_TELEMETRY` only affects the current shell session. For a
durable, persistent answer that survives across terminals and reboots:

```bash
gitaiflow --telemetry enable     # turn telemetry on, saved locally
gitaiflow --telemetry disable    # turn it back off
gitaiflow --telemetry status     # show the current saved answer
gitaiflow --telemetry history    # show every recorded answer, with version + timestamp
```

These exit immediately without running a summary. `GITAIFLOW_TELEMETRY`
still overrides the saved answer for the current process only -- useful
for CI without disturbing your durable local setting.

If enabled, a run sends limited operational information to the configured telemetry receiver, including the gitaiflow version, AI provider, model name, target type, changed-file count, estimated token counts, duration, operating system, and success status.

The following are not sent through telemetry:

* Repository name
* File paths
* File contents
* Git diff contents
* Git author or branch
* Commit messages
* AI-generated summary text

> Note: telemetry (and the local usage log) is only recorded on a normal summary run (`gitaiflow --path ...`), since that's the only path that calls an AI provider. `--changelog` runs read git history directly and don't touch telemetry or the usage log at all.

## Changelog Generation

```bash
gitaiflow --changelog --since 2026/08/01 --path .          # exact date, through today
gitaiflow --changelog --since "3 days ago" --path .        # relative, through right now
gitaiflow --changelog --since "2 weeks ago" --until "3 days ago" --path .
```

`--since` (required with `--changelog`) and `--until` (optional) each accept either:

* an exact date, `YYYY/MM/DD` (e.g. `2026/08/01`), or
* a relative expression, `<N> minute(s)/hour(s)/day(s)/week(s)/month(s) ago` (e.g. `"3 hours ago"`, `"2 weeks ago"`) -- years are not a supported unit.

If `--until` is omitted, an exact `--since` defaults to through the end of today; a relative `--since` defaults to right now. A range that resolves entirely before the repository's first commit, or into the future, is rejected upfront with an error rather than silently producing an empty changelog.

`gitaiflow` resolves `<remote>/<base-branch>` the same way a normal summary run does, then builds the changelog primarily from change-summary JSON artifacts already generated for that range -- keeping only the newest artifact touching any given file, so overlapping runs don't produce duplicate entries -- and falls back to `git log`, scoped to that same remote branch only, when no artifacts exist yet for the range. Either source is bucketed by conventional-commit type and prepended as a new entry to `CHANGELOG.md` above whatever's already there -- existing entries are never modified except to merge in new content for a still-open version label.

If the change-summary was generated with a custom `-o`/`--output-dir`, pass the same value to `--changelog`.

## Limitations

* An AI provider must be configured before `gitaiflow` can generate summaries.
* Local usage limits are courtesy guardrails and can be removed by the user.
* Secret redaction is best-effort pattern matching; generated summaries should be reviewed before being shared.
* Token and cost estimates are approximate and are not provider billing measurements.

## Links

* **Homepage:** https://gitlab.com/codefleet-labs/gitaiflow
* **Repository:** https://gitlab.com/codefleet-labs/gitaiflow
* **Issues:** https://gitlab.com/codefleet-labs/gitaiflow/-/issues
* **Documentation:** https://docs.djangoplay.org/view#projects/gitaiflow/

## License

`gitaiflow` is released under the MIT License.
