Vector : local code summariser

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 3: Slow and Steady

What I Built

Everyone has opened an unfamiliar repo and spent the first hour just trying to work out what it does. Vector is my lazy answer to that hour.

Vector is a local code summariser. Give it a file, a GitHub repo, or an entire project folder, and it tells you what the code is for before you read any of it. Every file gets a TL;DR, its purpose, key functions with line ranges, dependencies, and gotchas. For a whole project it also writes an overview: tech stack, architecture, a directory map, entry points, how to run it, and an ordered "start reading here" list.

The laziest part is watch mode. Point Vector at a folder, edit a file, and a fresh summary shows up on its own a few seconds later. You never have to ask.

It's for anyone who reads more code than they write: students inheriting a messy assignment, Hacktoberfest contributors landing in a new repo, and anyone who has ever said "wait, what does this module do?"

Demo

https://vector-frontend-dxot.onrender.com

Code

https://github.com/amitsinha-cell/vector.git

How I Built It

The open pieces

• Gemma 4 E4B is the default model. I also use Gemma 4 E2B as the light option and Qwen2.5-Coder 7B as "deep mode."
• Ollama runs inference locally.
• tree-sitter splits code by structure (functions, classes), not by size.
• FastAPI + SQLite (FTS5) handle the backend, caching, history, and search.
• watchdog powers the folder watcher.
• The frontend is React + Vite + TypeScript, started in Lovable. I built the backend with Antigravity, and the specs and design decisions were mine.

My hardware is the whole story. I built and tested this on an HP Victus laptop with an RTX 4050 (6 GB VRAM, 50W TGP). That is not a big machine, and it shaped every decision:

1. Structure-aware chunking. Small models get lost in long files. Vector parses the file, summarises each function or class, then rolls those up into a file-level summary. If parsing fails, it falls back to overlapping line windows.
2. Hierarchical project mode. A whole folder will never fit in one context window. Vector summarises files, then directories, then the project. Only the top-ranked files (entry points, manifests, most-imported modules) get full LLM summaries. The rest get a one-line description built from their function and class names, with no model call at all.
3. Cache by content hash. The cache key is the file's contents plus the model and prompt version. Re-uploading an unchanged folder returns almost instantly, so the GPU only works on what changed.
4. One GPU queue. Watcher jobs and manual requests never run at the same time on the same card.
5. Schema-checked output. Every result is validated against a fixed JSON schema, with one repair retry before returning a partial result with a warning.

What went wrong. gemma4:e4b is 6.6 GB on disk and my card has about 5 GB free, so part of it runs on CPU. I added a smaller-model retry and kept E2B one dropdown away.

My favourite bug: the UI said "Ollama isn't running" while Ollama was fine. The real cause was a CORS preflight rejection. Vite had moved to port 8081 and the backend's allowlist didn't include it, so the browser never read /health. The fix was easy, but the real lesson was that "backend unreachable" and "Ollama down" are different failures and the UI should say which one it is. It does now.

Why Does Open Innovation Matter?

Your code stays on your machine. A code summariser is a poor fit for a closed API. People paste private, unreleased, or employer-owned code into it. With local models the code never leaves the laptop. The UI shows a "100% local" badge, and a hosted fallback exists only as an opt-in setting that is off by default, with a warning before any code is sent.

Watch mode is only practical when inference is free. An assistant that re-summarises every time you save a file would run up an API bill quickly. Locally, the only cost is electricity.

Swapping models is a dropdown. I could try Gemma 4 against Qwen2.5-Coder on my own files and pick per task. A closed API doesn't let me do that.

It works offline. Once the models are pulled, Vector needs no internet except for GitHub repo mode.

Customising is possible. Because the weights are open, I can fine-tune a small Gemma on code-summary pairs next. I've fine-tuned small Gemma models before, and that path is closed with a hosted API.

Where closed still wins. Large frontier models write better summaries of huge, tangled files. For "tell me what this folder is about," a small local model with good chunking was good enough, and it was private.

The Lazy Payoff

For example: "A 40-file project that took me about 120 minutes to understand by reading now takes 30 minutes, and the cached re-run takes 10 seconds."

Prize Categories

• Gemma: Gemma 4 E4B and E2B are the core models.
• GitHub: repo ingestion. [Keep this only if repo mode really uses the GitHub API or clones through GitHub.]