Metadata-Version: 2.3
Name: git-issue-fixer
Version: 0.1.0
Summary: Fetch GitHub issues, fix them with an Ollama LLM, and open a pull request.
Author: Abu Haider Siddiq
Author-email: Abu Haider Siddiq <dmsbilas@yahoo.com>
Requires-Dist: langchain-ollama>=0.3.0
Requires-Dist: langgraph>=1.2.11
Requires-Dist: pydantic>=2.13.4
Requires-Dist: python-dotenv>=1.2.2
Requires-Dist: pygithub>=2.3.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# git-issue-fixer

A pip-installable agent you can drop into **any Python project**. It reads open GitHub issues from a repo you configure, clones that repo, uses an Ollama LLM to patch files, and opens a pull request.

You do not copy this source into your app. Install the package, add a `.env` (or export environment variables), and run the command.

---

## What you need

- Python 3.10+
- `git` on your PATH
- An [Ollama](https://ollama.ai) server with the model you name in `.env`
- A GitHub personal access token with **repo** scope

The target GitHub repo is whatever you set in `GIT_REPO_URL`. It does not have to be the project where you installed the package.

---

## 1. Install into your project

From the folder that contains this package (or a built wheel):

```bash
cd your-python-project
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

pip install /path/to/git_issue_fixer_agent
```

Editable install while developing the agent itself:

```bash
pip install -e /path/to/git_issue_fixer_agent
```

With uv:

```bash
uv add /path/to/git_issue_fixer_agent
```

That installs the `git-issue-fixer` console script into your environment.

You can also add it in `pyproject.toml`:

```toml
[project]
dependencies = [
  "git-issue-fixer @ file:///absolute/path/to/git_issue_fixer_agent",
]
```

---

## 2. Configure (`.env` in *your* project)

Run this **in the directory you want to work from** (usually your project root):

```bash
git-issue-fixer init
```

That writes a `.env` file if one does not already exist. Edit it:

```env
# Required
GITHUB_TOKEN=ghp_your_token_here
GIT_REPO_URL=https://github.com/owner/your-repo.git

# Ollama (required to actually run)
OLLAMA_HOST=http://localhost:11434
OLLAMA_MODEL=qwen3.6:27b

# Optional
# ISSUE_LIMIT=5
# MAX_REPAIRS=3
# ISSUE_BRANCH_PREFIX=fix/
# GIT_ISSUE_FIXER_WORK_DIR=repo_work
# MAX_ANALYZE_FILE_BYTES=40000
# LLM_TEMPERATURE=0.9
```

Add `.env` to your project's `.gitignore`. Do not commit tokens.

### How config is loaded

1. `--env-file /path/to/file` if you pass it
2. Else `.env` in the **current working directory**
3. Else variables already in the process environment

Variables already set in the shell are **not** overwritten by the file.

You can skip `.env` entirely:

```bash
export GITHUB_TOKEN=ghp_...
export GIT_REPO_URL=https://github.com/owner/your-repo.git
export OLLAMA_HOST=http://localhost:11434
export OLLAMA_MODEL=qwen3.6:27b
git-issue-fixer
```

### Environment variables

| Variable | Required | Default | Meaning |
|---|---|---|---|
| `GITHUB_TOKEN` | yes | — | GitHub PAT (`repo` scope) |
| `GIT_REPO_URL` | yes | — | Repo whose issues will be fixed |
| `OLLAMA_HOST` | no | `http://localhost:11434` | Ollama base URL |
| `OLLAMA_MODEL` | no | `qwen3.6:27b` | Model name on that host |
| `ISSUE_LIMIT` | no | `5` | How many open issues to process |
| `MAX_REPAIRS` | no | `3` | Repair attempts after failed tests |
| `ISSUE_BRANCH_PREFIX` | no | `fix/` | Prefix for new branches |
| `GIT_ISSUE_FIXER_WORK_DIR` | no | `repo_work` | Clone directory (relative to cwd) |
| `MAX_ANALYZE_FILE_BYTES` | no | `40000` | Max source bytes sent to the LLM |
| `LLM_TEMPERATURE` | no | `0.9` | Ollama temperature |

---

## 3. Run it

From your project directory (where `.env` lives):

```bash
git-issue-fixer
```

Useful flags:

```bash
git-issue-fixer --help
git-issue-fixer --env-file /path/to/.env
git-issue-fixer --limit 1
git-issue-fixer init --env-file /tmp/issue-fixer.env
python -m git_issue_fixer --env-file .env
```

### What happens

For each open issue (up to `ISSUE_LIMIT`):

1. Clone `GIT_REPO_URL` into `repo_work/` (or `GIT_ISSUE_FIXER_WORK_DIR`)
2. Analyze **only files inside that clone**
3. Generate and apply a patch there
4. Commit on a short branch (`fix/<first-3-title-words>-<10-char-random>`)
5. Push and open a pull request

The agent does not edit files in *your* local project unless that project is the GitHub repo you pointed `GIT_REPO_URL` at.

---

## 4. Call it from Python

In any script, notebook, or app that uses the same virtualenv:

```python
from git_issue_fixer.main import configure, run

configure()                    # loads .env from the current directory
run()
```

Custom env file and issue cap:

```python
from git_issue_fixer.main import configure, run

configure(env_file="/path/to/.env", issue_limit=2)
run()
```

Or invoke the CLI from code:

```python
from git_issue_fixer.cli import main

main(["--env-file", ".env", "--limit", "1"])
```

Load settings without running the agent:

```python
from git_issue_fixer.config import load_settings

settings = load_settings(".env")
print(settings.git_repo_url, settings.ollama_host)
```

---

## 5. Typical layout in *your* project

```
your-python-project/
├── .venv/
├── .env                 # gitignored; GITHUB_TOKEN, GIT_REPO_URL, Ollama
├── pyproject.toml       # lists git-issue-fixer as a dependency
├── src/your_app/
└── repo_work/           # created at runtime, cloned target repo
```

`repo_work/` is a throwaway clone. You can add it to `.gitignore`.

---

## 6. CI / automation

Example GitHub Actions step (secrets in the repo settings, not in `.env`):

```yaml
- name: Run git-issue-fixer
  env:
    GITHUB_TOKEN: ${{ secrets.ISSUE_FIXER_TOKEN }}
    GIT_REPO_URL: https://github.com/${{ github.repository }}.git
    OLLAMA_HOST: http://ollama.internal:11434
    OLLAMA_MODEL: qwen3.6:27b
    ISSUE_LIMIT: "1"
  run: git-issue-fixer
```

The job environment must be able to reach Ollama (`OLLAMA_HOST`).

---

## Troubleshooting

| Problem | What to check |
|---|---|
| `command not found: git-issue-fixer` | Activate the venv where you ran `pip install`. |
| Missing `GITHUB_TOKEN` / `GIT_REPO_URL` | Run `git-issue-fixer init` in that directory and edit `.env`, or pass `--env-file`. |
| `Env file not found` | Path to `--env-file` is wrong; it is resolved from the current working directory. |
| `Failed to clone` | Token needs **repo** scope; URL should be `https://github.com/owner/repo.git`. |
| `[Errno 65] No route to host` / connection refused | `OLLAMA_HOST` is unreachable. Try `curl "$OLLAMA_HOST/api/tags"`. |
| Wrong repo got cloned | `GIT_REPO_URL` is the target to fix, not necessarily the project you installed the package into. |
| No files changed | The agent only writes inside `repo_work/`. Paths outside that clone are skipped. |

---

## License / version

Package name: `git-issue-fixer`  
Import name: `git_issue_fixer`  
CLI: `git-issue-fixer`  
Requires: Python >= 3.10
