Metadata-Version: 2.4
Name: gitaiflow
Version: 1.0.2
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 environment variables or a `.gitaiflow.env` file in the repository root.

### 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 `.gitaiflow.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 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

Telemetry is **disabled by default**.

If explicitly enabled with:

```bash
export GITAIFLOW_TELEMETRY=true
```

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

On the first telemetry-enabled run, `gitaiflow` prints the exact telemetry payload to stdout.

## 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

## License

`gitaiflow` is released under Apache License.
