# mu-gemini-coder (v0.0.3)

An ultra-lightweight, minimalist, resource-friendly AI development companion built with **GTK3** and **Vala**. It provides a clean chat interface to communicate with Google's Gemini models, allowing the AI to read and write files directly within smaller software workspaces. It avoids Electron/VS Code bloat by design and utilizes **Geany** as an external code viewer and editor.

Distributed under the **GNU General Public License v2.0 or later (GPLv2+)**.

---

## Features
- **File Read/Write Execution**: Gemini uses autonomous tool functions to read code structure or save generated files directly inside your workspace directory.
- **Dynamic Rule Toggle (Allow AI Explanations)**: An interactive checkbox over the chat window allows switching from strict, full-file auto-write mode into a conversational mode. If enabled, the AI can speak freely, explain bugs, show diffs, and provide architectural advice without strict markdown constraints.
- **Target Filename Binding**: Automatically forces the AI to output exact target file headers (`--- File: filename.vala ---`) right before generated code blocks to prevent mapping mismatches.
- **External Editor Hook**: One-click integration with Geany for lightning-fast file editing with automatic real-time reload prompts when files are written by the AI.
- **Alphabetical File Workspace**: Automatically maps workspace contents in a clean, left-aligned, and strictly sorted (A-Z) file explorer list.
- **System Build Console with Autoscroll**: Dedicated terminal panel with real-time autoscrolling for both compilation readouts (`make`, `make clean`) and binary run processes, featuring an independent "Clear Console" utility button.
- **Session State Persistence**: Automatically generates a local `session.json` configuration inside each project folder to preserve past conversational state.
- **Desktop Launcher Integration**: Fully self-contained menu shortcut with native pre-flight error validation alerting you visually if keys are not exported.

---

## Prerequisites & API Key Setup

This application requires a **free Gemini API key** from Google AI Studio. The free tier does not require a subscription or credit card.

1. Navigate to the official [Google AI Studio API Dashboard](https://google.com).
2. Click **"Create API key"** and copy the generated token string. *(Note: You might have to create a new project first to see this option!)*
3. Export the key globally inside your local user profile environment configuration:
   
   ```bash
   # Add this line to your ~/.bashrc or ~/.profile file: (Note MU: .bashrc in Mint)
   export GEMINI_API_KEY="your_actual_copied_api_key_here"
   ```

---

## Installation Guide

### Option A: Linux Mint (22.3+) Installation

#### 1. Install Build Tools and Compiler Tooling:
```bash
sudo apt update
sudo apt install valac libgtk-3-dev libjson-glib-dev python3 python3-pip geany zenity
```

#### 2. Install Required Python SDK Dependencies:
```bash
pip3 install google-genai

# Or if you encounter managed environment blocks:
pip3 install google-genai --break-system-packages
```

#### 3. Build the Native Debian Package:
```bash
make deb
```

#### 4. Install the Generated Package:
```bash
sudo dpkg -i mu-gemini-coder_1.0.0_all.deb
```

---

### Option B: Puppy Linux (Bookworm Edition) Installation

Due to the ultra-lightweight architecture of Puppy Linux, you must ensure the core development devx package and base dependency binaries are registered locally.

#### 1. Setup Build Environment:
Open the **Puppy Package Manager (PPM)** or run your package command utility to install the following dependencies:
- `valac`
- `libgtk-3-dev`
- `libjson-glib-1.0-dev`
- `geany`
- `zenity`

#### 2. Setup Python SDK Pipeline:
Because Puppy Bookworm enforces system-wide python managed environments by default, install the SDK via the flag below:
```bash
pip3 install google-genai --break-system-packages
```

#### 3. Build and Install via Makefile Tooling:
```bash
# Compile and create local filesystem layout binaries
make

# Install globally to system layout paths
sudo make install
```

---

## Makefile Automation Commands Summary

The project repository includes a structured `Makefile` for localized management tasks:

- **`make`**: Compiles the raw Vala application locally for immediate testing (`./mu-gemini-coder`).
- **`make deb`**: Packaged archive engine compiling a native Debian package asset (`.deb`).
- **`make install`**: Manually provisions build binaries, backend scripts, and application menu pointers over to system folders (`/usr/bin/`, `/usr/share/`).
- **`make uninstall`**: Completely removes all installed software binaries and metadata footprints from your machine.
- **`make clean`**: Purges transient development outputs, generated files, and compilation directories.

---

## Usage Workflow

1. Open **mu-gemini-coder** from your desktop environment menu layout (located under the **Development** or **Programming** section).
2. Click **"Browse Folder"** to open or instantiate your codebase folder target path.
3. Click **"Open File in Geany"** to spin up your external code-editing workspace view.
4. Input instructions inside the chat prompt entry layout (e.g., *"Create a hello world messagebox in vala and gtk3 and makefile including make deb and readme"*).
5. Watch files automatically manifest. Your external Geany window will dynamically update and prompt you to reload changes in real-time.
6. Use the **"Allow AI Explanations"** checkbox whenever you hit an architectural blockade and want the AI to explain error stack traces instead of overriding full files.