Skip to content

spec.md

Latest commit

 

History

History
37 lines (28 loc) · 2.78 KB

spec.md

File metadata and controls

37 lines (28 loc) · 2.78 KB
Raw

Overview
A tiny, self‑contained coding assistant that runs completely offline. It loads a locally‑stored Gemma 4 GGUF model and, given a short code snippet, returns either a refactoring suggestion or a plain‑language explanation. The tool is a command‑line program written in Python, has no editor coupling, and depends only on standard Python packages (torch, transformers, sentencepiece). It is designed for solo developers who want fast, private AI help without any internet round‑trip.

Tech Stack

  • Language: Python 3.10+
  • Model format: GGUF (Gemma 4) – one file, e.g., gemma-4-q4_k_m.gguf
  • Inference: torch ≥ 2.3 with the transformers library for tokenizer/model loading
  • Tokenizer: sentencepiece (bundled with transformers)
  • Dependency management: ordinary pip + requirements.txt (no uv)
  • Packaging: single entry‑point script gemma_code_helper.py invoked via python gemma_code_helper.py

Architecture

+-------------------+        +-------------------+        +-------------------+
|  CLI Frontend    | --->   |  Inference Engine | --->   |  Output Formatter |
| (argparse)       |        | (torch + HF)      |        | (plain text)      |
+-------------------+        +-------------------+        +-------------------+
  1. CLI Frontend parses --mode {refactor,explain} and reads a code snippet from --file or STDIN.
  2. Inference Engine loads the GGUF model once at startup, tokenizes the input, builds a prompt that instructs Gemma 4 to either refactor or explain, runs a single forward pass, and returns the raw generation.
  3. Output Formatter strips special tokens, trims whitespace, and prints the result to STDOUT.
    All components run in the same process; no network calls, no editor plugin, no external services.

Core Features (max 2)

  1. Refactor Mode – Given a snippet, the model proposes a cleaned‑up version (e.g., removing dead code, simplifying loops, applying PEP‑8).
  2. Explain Mode – Given a snippet, the model returns a concise, plain‑language description of what the code does (intent, algorithm, key variables).

Both modes share the same model and inference path; the only difference is the instruction prefix added to the prompt.

No Zed integration, no complex server, no multiple endpoints—just a single binary‑like script that works on any local file.

Estimated size: roughly 120 lines of Python (including docstrings and help text) – well within the 5‑iteration target for an autonomous agent.
Why it works: By stripping away every external plumbing (no RPC server, no editor plugin, no uv) and focusing on the core value—offline, low‑latency AI‑assisted coding—we obtain a minimal viable tool that can be built, tested, and shipped quickly.