Metadata-Version: 2.4
Name: review-assist
Version: 0.4.2
Summary: CLI tool to assist with reviewing merge requests, including AI-assisted automated review
Project-URL: Homepage, https://gitlab.com/rmenage/review-assist
Project-URL: Issues, https://gitlab.com/rmenage/review-assist/-/work_items
Project-URL: Repository, https://gitlab.com/rmenage/review-assist.git
Author-email: Rija Ménagé <rm+py@review-assist.p-t.io>
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: automated review,backlog,cli,code review,llm generated,merge requests,review comments,review pipeline
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Scheduling
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.10
Requires-Dist: httpx-retries>=0.5.0
Requires-Dist: httpx>=0.28.1
Requires-Dist: jsonschema>=4.26.0
Requires-Dist: lmstudio>=1.5.0
Requires-Dist: openai>=2.33.0
Requires-Dist: rich>=14.3.3
Requires-Dist: types-jsonschema>=4.26.0.20260508
Description-Content-Type: text/markdown

# Review-Assist
![Flake8 Status](
https://review-assist.p-t.io/assets/images/badges/linter-badge.svg?dummy=8484744)
![Tests Status](https://review-assist.p-t.io/assets/images/badges/test-badge.svg?dummy=8484744)
![Coverage Status](https://review-assist.p-t.io/assets/images/badges/coverage-badge.svg?dummy=8484744)
![CI/CD](https://gitlab.com/rmenage/review-assist/badges/main/pipeline.svg)

CLI tool to assist with change requests for GitLab (MRs), requesting review and 
bootstrap the process with auto-review from a local LLM inference server (BYOM)
you configure.

!!! warning

    This tool is in its early stage of development, there will be breaking changes.


## Installation

### Using `pipx`

```bash
$ pipx install review-assist
```

### Using `uv`

```bash
$ uv tool install review-assist
```

### From source

Clone the repo, build and install the CLI tool:
```bash
$ git clone https://gitlab.com/rmenage/review-assist
$ cd review-assist
$ make clean
$ make local-install && make build && make build-binary && make install
```

The tool will be installed in ``~/.local/bin/ra``.
You can run it by running ``ra`` from the command line.

## Configuration

You can view the current configuration by running:
```bash
ra config
```
 
The first time you run that command, a default configuration will be created if none exists.

The default location for the configuration is ``~/.config/ra/review-assist.cfg``.

You can also pass the `-c PATH` or `--config-file PATH` option to override the default configuration with a custom config file.

## Usage

First, ensure you have installed and started a local LLM server.
For example for headless LM Studio:
```bash
$ curl -fsSL https://lmstudio.ai/install.sh | bash
$ lms get google/gemma-3-1b
$ lms load google/gemma-3-1b -c 32768
$ lms server start
```

Next, to review a Gitlab merge request, pass the project name and the merge request IID to the command:
```bash
ra changes review --project my-namespace/my-project --change-request 42
```

## Supported LLM backends and models

Those are the inference engine currently supported:

1. LM Studio (default)
2. OpenAI API generic backend

The default configured model is `google/gemma-3-1b`, as its small size should fit most computers and allows for faster automated tests.

However, it's not going to provide many good insights.
I'm using (On a 48GB unified RAM MacBook Pro) the following models to test the tool with and also to review this project's code with:

With MLX format (Mac only): 

* google/gemma-4-26b-a4b-qat
* mistralai/devstral-small-2-2512
* qwen3.6-35b-a3b

With GGUF format: 

* unsloth/Qwen3.5-9B-GGUF



## Supported Git servers

1. GitLab

## Cookbook

### Install and start a local llama server (to use with the OpenAI backend)

```bash
$ brew install llama.cpp
$ env LLAMA_CACHE="models/unsloth/Qwen3.5-9B-GGUF" \
llama-server \
    -hf unsloth/Qwen3.5-9B-GGUF:UD-Q4_K_XL \
    --temp 0.6 \
    --top-p 0.95 \
    --top-k 20 \
    --min-p 0.00 \
    -ngl 99 \
    -c 131072 \
    -np 1 \
    -fa on \
    --alias "unsloth/Qwen3.5-9B-GGUF" \
    --port 4321 \
    --reasoning off 
```
>**Note**: the above command will start a server on port 4321 and the first time it will download the model
> from HuggingFace, and store it in the cache directory ``models/unsloth/Qwen3.5-9B-GGUF`` in your home directory.

The config file at ``~/.config/ra/review-assist.cfg`` should look like this:
```aiignore
[adapters]
local_llm.provider = openai
local_llm.model = unsloth/Qwen3.5-9B-GGUF
local_llm.api_url = http://127.0.0.1:4321
local_llm.api_key = nokey
git_server.base_url = https://gitlab.com/api/v4/projects
git_server.private_token = my-token
```

## Troubleshooting

You can increase logging verbosity by passing `-v` one or more times.
That will also show the config file and log file location in terminal output.

If passed three times (`-vvv`), it will also show the full stack trace when an error occurs,
and the posted reviews will have a debug panel with LLM details.

The log file is located at `~/.local/state/ra/review-assist.log`.

### Configuration errors

!!! failure
    ```
    RAConfigError: Configuration error with source:
     ~/.config/ra/review-assist.cfg
    Config file permissions are incorrect (it should be read/write only for owner - chmod 600)
    ```

Because the configuration can hold private token for the git server API, 
It must not be readable by other users on the system.
Problem can be fixed by changing the permissions:
```bash
$ chmod 600 ~/.config/ra/review-assist.cfg
```
The default configuration file (the example used here), created on first run has already the correct permissions.
This error is more likely to happen when supplying a custom configuration file (with the `-c` parameter)
and forgetting to change the permissions beforehand.

### LMStudio errors

!!! failure

    `lmstudio.LMStudioServerError: Chat response error: The number of tokens to keep from the initial prompt is greater than the context length. Try to load the model with a larger context length, or provide a shorter input`

The context is too small to fit all the tokens generated by the review.
You can try increasing the context size to the maximum possible for a given model.
E.g: for the default model, `google/gemma-3-1b`, the maximum context size is 32768,
so make sure to set the context to that size:

```bash
$ lms load google/gemma-3-1b -c 32768
```

For `qwen3.6-35b-a3b`, the maximum is 262144, but I found acceptable and memory-saving to use half of that
```bash
$ lms load qwen3.6-35b-a3b -c 131072
```

!!! failure
    
    `lmstudio.LMStudioServerError: Model get/load error: Model loading was stopped due to insufficient system resources. Continuing to load the model would likely overload your system and cause it to freeze. If you think this is incorrect, you can adjust the model loading guardrails in settings.`

In my experience, it indicates that the model I selected is too big to fit the current available memory.
Try selecting a smaller model is a way of resolving that issue.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md)
