Local AI Code Refactor Bot

A local, containerized web application that uses a Large Language Model (LLM) to refactor, document, or transform code projects. It runs entirely offline using Ollama and a Python FastAPI backend.

Features

• Local by Default: Refactoring runs against your local Ollama model.
• Optional Web Research: If enabled, the app fetches public web snippets to enrich context.
• Stack-Aware Prompting: Loads framework/language context from JSON files in context/ using extension and filename mapping rules.
• Zip or Single File Input: Upload either a source code zip or one supported code/config file, and get a refactored zip back.
• Multi-File Aware: Can generate entirely new project structures (e.g., Python to Java ports).
• Hardware Agnostic: Runs on standard Linux servers (CPU) or NVIDIA-equipped workstations (GPU).

Prerequisites

• Docker Desktop or Docker Engine
• RAM: 16GB Minimum (for CPU mode)
• GPU (Optional): NVIDIA GPU with 12GB+ VRAM for accelerated processing

Quick Start

1. Choose your Mode

Option A: Standard / CPU Mode (Linux Servers) Use the standard compose file. This is best for servers without dedicated GPUs.

docker compose up --build -d

Option B: NVIDIA GPU Mode (Local Workstation) Use the GPU-optimized compose file.

docker compose -f docker-compose.gpu.yml up --build -d

2. Download the Model

You must download the model once after starting the containers. We use qwen2.5-coder:14b for the best balance of logic and speed.

Linux / Mac:

docker exec -it ollama_backend ollama pull qwen2.5-coder:14b

Windows (Git Bash):

winpty docker exec -it ollama_backend ollama pull qwen2.5-coder:14b

3. Usage

1. Open your browser to http://localhost:8000.
2. Upload either a .zip project archive or one supported source/config file.
3. Enter instructions (e.g., "Add Typescript interfaces" or "Convert to Java Spring Boot").
4. (Optional) Enable Add web research to prompt context.
5. (Optional) Provide a custom query and web snippet count (1-10).
6. Click Process.
7. Wait for processing to finish (logs are available via docker compose logs -f app) and download the result.

Project Structure

.
├── app.py                 # FastAPI backend & LLM logic
├── Dockerfile             # Python environment build
├── docker-compose.yml     # Standard CPU/Universal config
├── docker-compose.gpu.yml # NVIDIA GPU config
├── requirements.txt       # Python dependencies
├── context/              # Stack context JSON files + mapper
│   ├── mapper.json       # Extension/filename to context-file mapping
│   └── *.json            # Detailed stack guidance and docs links
└── templates/
    └── index.html         # Frontend UI

Troubleshooting

• Logs: Run docker compose logs -f app to see what the AI is writing in real-time.
• Timeout: The application is configured to wait indefinitely for the LLM. If you experience network timeouts (e.g. Nginx 504 Gateway Time-out), check your reverse proxy settings.
• Memory: If the container crashes on large files, try a smaller model like qwen2.5-coder:7b.

GitHub Action (Pipeline-Only, No UI)

This repository now includes a workflow at .github/workflows/repo-converter.yml that runs end-to-end conversion in GitHub Actions.

Workflow Inputs

• context_repo: HTTPS URL of the source repository to use as conversion context.
• destination_repo: HTTPS URL of the destination repository that receives converted code.
• destination_stack: Target technology stack for conversion (for example, Spring Boot, FastAPI, Node.js).
• github_username: GitHub username used for HTTPS auth (x-access-token recommended for PAT/app tokens).
• model_name: Ollama model to pull inside the action before conversion (default: qwen2.5-coder:14b).

How It Works

1. Clones the context repo (source).
2. Clones the destination repo on main.
3. Starts an Ollama service container and waits for health readiness.
4. Pulls the selected model in the workflow.
5. Runs AI conversion across supported files using github_action_runner.py.
6. Clears destination repo content before copy (preserves .git and existing README.md).
7. Removes untouched original context/source files so they are not published with converted output.
8. Copies converted output into destination repo (source README.md is skipped to preserve destination README.md).
9. Commits and pushes to the destination repo main branch.

Required GitHub Settings

• OLLAMA_URL is set automatically by the workflow to the local Ollama service endpoint.
• Model selection is controlled by the workflow input model_name.
• GITHUB_TOKEN is used by default for Git authentication.
• This workflow starts an ollama/ollama service container and points the converter to http://127.0.0.1:11434/api/generate so it behaves like a local install directly inside GitHub Actions.
• If either repository is private (or in another org), add:
  • CONTEXT_REPO_TOKEN (secret): token that can read the context repo.
  • DESTINATION_REPO_TOKEN (secret): token that can read/write the destination repo.

Manual Trigger

Go to Actions → Repository Converter → Run workflow and provide the required inputs (plus optional github_username if needed).