{"slug": "build-sweepy-a-local-first-ai-downloads-organizer", "title": "Build Sweepy — A Local-First AI Downloads Organizer", "summary": "A developer built Sweepy, a local-first desktop file organizer that uses Google's open-weight Gemma 3 1B model running via Ollama to propose structured folder paths for messy directories like Downloads and Desktop. The tool passes only file metadata to the local model, which returns validated JSON suggestions in batches of 15, while a separate Python FastAPI backend performs all filesystem moves with safety checks and one-click undo. The project is open source on GitHub as a Next.js and FastAPI monorepo.", "body_md": "*This is a submission for the [Hacktoberfest Open-Source AI Challenge Week 3: Slow and Steady](https://dev.to/challenges/hacktoberfest-week3-2026-10-19)*\n\n## \n  \n  \n  What I Built\n\n**Sweepy** is a local-first, privacy-respecting desktop file organizer that brings order to your most chaotic directories (like `Downloads` and `Desktop`) without manual sorting.\n\nInstead of dragging files one-by-one into subfolders or inventing filenames, Sweepy scans your messy directory, passes lightweight metadata to a locally running open-weight AI model (**Gemma 3 1B** via **Ollama**), and proposes clean, structured folder paths (e.g. `Documents/Invoices/`, `Images/2026-10/`, `Code/`).\n\n### \n  \n  \n  Who gets to be a little lazier because of it?\n\n- \n**Developers, students, and power users** who download dozens of invoices, PDFs, zip archives, scripts, and screenshots every day and dread the thought of spending their Sunday afternoon manually sorting files.\n- Anyone who wants the convenience of automated organization without uploading sensitive financial receipts, resumes, or private photos to cloud AI APIs.\n\n**Core Philosophy:** *AI recommends; deterministic application code executes; the user stays in control.*\n\n## \n  \n  \n  Demo\n\nCheck out the full walkthrough video demonstrating folder scanning, local Gemma 3 inference, inline path editing, safe execution, and 1-click Undo:\n\n**Direct Video Link:** [https://youtu.be/A21HS3Ggo1Y](https://youtu.be/A21HS3Ggo1Y)\n\n## \n  \n  \n  Code\n\n# Sweepy — Local-First AI Downloads Organizer\n\nSweepy is a desktop-first file organization tool that helps you organize messy folders (such as `Downloads`) without manual sorting.\n\nSweepy scans a folder, passes file metadata to a local AI model (**Gemma 3 1B** running via **Ollama**), and proposes clean destination folders and filenames. You review, edit, and approve suggestions before anything is moved.\n\n**Core Principle:** AI recommends; deterministic application code executes; the user stays in control.\n\n## Key Features\n\n- \n**Dashboard** : Track scanned files, pending reviews, generated suggestions, and completed operations. Live connection indicators for backend and Ollama.\n- \n**Secure Folder Scanning** : Fast directory enumeration with Windows native folder picker dialog and quick-folder shortcuts. Automatically ignores hidden files and system/application folders (`.git` ,`node_modules` ,`.venv` ). Never reads file contents.\n- \n**Local AI Inference** : Powered by Ollama running Google's`gemma3:1b` model. Categorizes files into structured folders (`Documents/Invoices/` …\n\n \n \n**GitHub Repository:** [https://github.com/Ahzem/sweepy.git](https://github.com/Ahzem/sweepy.git)\n\nThe codebase is organized as a clean monorepo:\n\n- \n**`apps/web`** : Next.js 16 (App Router), React 19, TypeScript, and Tailwind CSS.\n- \n**`apps/api`** : Python 3.11+ FastAPI backend with Pydantic v2 schemas and atomic JSON operation logging.\n- \n**`docs/architecture.md`** : Full system design, threat model, and Windows filesystem safety documentation.\n- \n**`scripts/dev.ps1`** : 1-click PowerShell launcher for Windows 11.\n\n## \n  \n  \n  How I Built It\n\nSweepy is built specifically around **local, open-weight AI inference**:\n\n1. \n**Local Model Ingestion (Ollama & Gemma 3 1B)** :\n   - We utilize Google's open-weight **Gemma 3 1B** (`gemma3:1b` ) running through Ollama at`http://127.0.0.1:11434` .\n  - By structuring requests with Ollama's native JSON mode (`format: \"json\"` ), Gemma 3 reliably returns validated JSON schemas containing proposed filenames, subfolder destinations, category classifications, and reasoning summaries.\n  - Files are batched in micro-chunks (15 items per batch) to ensure lightning-fast generation without context bottlenecking.\n2. \n**Deterministic Safety Architecture** :\n   - The AI only suggests paths; it never executes shell commands or touches the filesystem directly.\n  - All filesystem operations are handled by a dedicated Python backend with defense-in-depth safety:\n    - \n**Strict Path Confinement** : Enforces`target.resolve().relative_to(root.resolve())` to prevent directory traversal sequences (`../` ) or symlink escapes.\n    - \n**Collision Prevention** : If a destination file already exists, Sweepy automatically appends a safe counter suffix (e.g.`invoice (1).pdf` ) rather than overwriting.\n    - \n**Zero Deletions** : The codebase contains zero file deletion calls—files are only moved or renamed.\n    - \n**Rule-Based Fallback** : If Ollama is offline or busy, Sweepy automatically switches to deterministic keyword and extension rules so organization never fails.\n3. \n**Atomic 1-Click Undo** :\n   - Completed moves are logged in an atomic local ledger (`~/.sweepy/operations_log.json` ).\n  - If you ever change your mind, clicking **Undo Move** checks destination validity and reverses the move back to the exact original location.\n\n## \n  \n  \n  Why Does Open Innovation Matter?\n\nOpen innovation—specifically open-weight foundation models and local inference—is what makes an application like Sweepy viable:\n\n1. \n**Absolute Data Sovereignty** : Nobody wants their bank statements, contracts, or tax documents sent over the wire to a closed, third-party LLM cloud. By using open-weight Gemma 3 running locally on`127.0.0.1` , user data never leaves the computer.\n2. \n**Zero Recurring Costs & Zero Rate Limits** : Closed APIs charge per token, require credit cards, and throttle users. Open-weight models run infinitely on consumer hardware for free.\n3. \n**True Offline Utility** : Sweepy works on an airplane or without an internet connection.\n4. \n**Accessible Performance** : A 1-billion parameter model like Gemma 3 1B runs smoothly on everyday laptops while possessing more than enough reasoning power to categorize documents and identify timestamps.\n\n## \n  \n  \n  My Agent Session\n\nSweepy was built and pair-programmed end-to-end using **Google Antigravity IDE**.\n\nThe agent collaborated on:\n\n- Architecting the pnpm monorepo layout separating Next.js and FastAPI.\n- Writing the path traversal security checks and Windows reserved device name safeguards (`CON` ,`PRN` ,`AUX` ,`NUL` ).\n- Developing an automated 21-test pytest suite with a full end-to-end lifecycle test verifying simulated download file moves and byte-level Undo integrity.\n- Designing the desktop-first UI with inline destination editing and interactive review tables.\n\n## \n  \n  \n  The Lazy Payoff\n\n### \n  \n  \n  The \"Before\" Experience\n\nOpening `Downloads`, finding 140 miscellaneous files from the past month, scrolling endlessly to locate that one ticket or receipt, and spending 25 minutes manually creating folders like `Invoices`, `Photos`, and `Zips`.\n\n### \n  \n  \n  The \"After\" Experience with Sweepy\n\n1. Launch Sweepy and click **Downloads** .\n2. Click **Scan Folder** (takes 200 milliseconds).\n3. Gemma 3 1B groups everything into neat categories (`Documents/Invoices/` ,`Images/2026-10/` ,`Installers/` ,`Development/` ).\n4. Click **Review & Apply** (takes 2 seconds).\n\n**Time saved:** Over 20 minutes per cleanup session. It turns one of computing's most tedious chores into a single click, letting you be as lazy as possible while keeping your machine spotless.\n\n## \n  \n  \n  Prize Categories\n\n- \n**Primary Track:** Hacktoberfest Open-Source AI Challenge Week 3: Slow and Steady\n- \n**Category:** Open-Weight Models & Local AI Utility", "url": "https://wpnews.pro/news/build-sweepy-a-local-first-ai-downloads-organizer", "canonical_source": "https://dev.to/ahzem/build-sweepy-a-local-first-ai-downloads-organizer-15ei", "published_at": "2026-10-21 07:35:44+00:00", "updated_at": "2026-10-21 07:39:57.976049+00:00", "lang": "en", "topics": ["artificial-intelligence", "ai-tools", "large-language-models", "ai-products", "developer-tools"], "entities": ["Sweepy", "Ollama", "Gemma 3 1B", "Google", "GitHub", "Next.js", "FastAPI"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/build-sweepy-a-local-first-ai-downloads-organizer", "markdown": "https://wpnews.pro/news/build-sweepy-a-local-first-ai-downloads-organizer.md", "text": "https://wpnews.pro/news/build-sweepy-a-local-first-ai-downloads-organizer.txt", "jsonld": "https://wpnews.pro/news/build-sweepy-a-local-first-ai-downloads-organizer.jsonld"}}