DEV Community: thedarkking01

FolderZen-an-AI-Powered-File-Organizer

thedarkking01 — Sat, 24 Oct 2026 12:38:48 +0000

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

What I Built

FolderZen is a local AI-powered file organizer that turns a folder full of cryptically named documents — doc_12.pdf, final_v3.docx, scan_04.pdf — into a clean, categorized structure with meaningful names, without ever sending your files to the cloud.

You point it at a messy folder. It reads the content of your PDFs, Word documents, and text files, asks a local AI model what each one actually is, and suggests a descriptive filename, a category, and a destination folder. You review every suggestion in an editable table, preview the exact paths before anything moves, then approve and apply.

Who gets to be lazier: anyone whose Downloads folder looks like a crime scene. Students with assignment_FINAL_v3_REAL.docx. Freelancers with invoice_copy2.pdf. Anyone who has spent 10 minutes hunting for a file they definitely saved somewhere.

Step	What happens
1. Scan	Detects all files, reads metadata
2. Extract	Reads text from PDF, DOCX, TXT (up to 1500 chars)
3. AI suggest	Sends text to local `gemma3:1b` via Ollama
4. Review	Editable table — approve, reject, or edit each suggestion
5. Preview	Shows exact destination paths before touching anything
6. Apply	Moves approved files; never overwrites; blocks path traversal
7. Report	Success / failure summary

Demo

📹 Add your screen recording or GIF here — record with OBS, ShareX, or Windows Game Bar (Win+G) pointing at the Streamlit app on localhost:8501.

Sample results from the included sample_files/ folder:

Messy filename	AI suggestion	Category	Reason
`doc_12.pdf`	`PythonInterviewNotes.pdf`	Tech	Contains Python interview prep notes covering data structures and algorithms
`scan_04.pdf`	`Electricity_Bill_October.pdf`	Finance	Appears to be a utility bill with account number and amount due
`final_v3.docx`	`FolderZen_Project_Proposal.docx`	Work	Contains a project proposal with objectives and timeline
`resume_draft.docx`	`Jane_Doe_Resume.docx`	Personal	Resume document listing skills and work experience

Code

thedarkking01 / FolderZen-an-AI-Powered-File-Organizer

FolderZen 🗂️

Local AI-powered file organizer. No cloud. No API keys. Your files stay on your machine.

FolderZen scans a messy folder, reads document content, and uses a local AI model (via Ollama) to suggest meaningful filenames, categories, and destinations — then lets you review and approve every change before anything moves.

Quick start

# 1. Clone
git clone https://github.com/YOUR_USERNAME/FolderZen.git
cd FolderZen

# 2. Create virtual environment
python -m venv .venv
.venv\Scripts\activate      # Windows
# source .venv/bin/activate  # macOS / Linux

# 3. Install dependencies
pip install -r requirements.txt

# 4. Pull the AI model (one-time)
ollama pull gemma3:1b

# 5. Run
streamlit run app.py

Generate sample files (optional)

python create_samples.py

Then point the app at the sample_files/ folder.

Run tests

pytest tests/ -v

How it works

Step	What happens
1. Scan	Detects all files, reads metadata
2. Extract	Reads text from PDF, DOCX, TXT (up

…

View on GitHub

Project structure:

FolderZen/
├── app.py               # Streamlit UI — all 4 steps
├── file_scanner.py      # Folder scanning and metadata
├── document_reader.py   # PDF, DOCX, TXT text extraction
├── ai_organizer.py      # Ollama prompt + JSON response parser
├── file_operations.py   # Safe move/rename with collision detection
├── create_samples.py    # Generates demo files
├── requirements.txt
└── tests/
    ├── test_scanner.py          # 6 tests
    └── test_file_operations.py  # 9 tests — 15 passing total

Quick start:

git clone https://github.com/thedarkking01/FolderZen-an-AI-Powered-File-Organizer
cd FolderZen

python -m venv .venv
.venv\Scripts\activate        # Windows
# source .venv/bin/activate   # macOS / Linux

pip install -r requirements.txt
ollama pull gemma3:1b
streamlit run app.py

Run tests:

pytest tests/ -v

How I Built It

Open-source AI used: Gemma 3 1B by Google, running locally via Ollama.

The core AI loop lives in ai_organizer.py. For each readable file, FolderZen:

Extracts up to 1500 characters of text using PyMuPDF (PDF) or python-docx (DOCX)
Sends a structured prompt to gemma3:1b via the Ollama Python client
Parses the model's JSON response — category, suggested filename, destination folder, and a one-sentence reason
Falls back gracefully if the model returns malformed output

The prompt is deliberately minimal to keep the 1B model fast and on-task:

You are a file organizer. Given a document snippet, return ONLY a JSON object with:
- "category": one of [Work, Finance, Personal, Education, Legal, Medical, Tech, Other]
- "suggested_name": descriptive filename without extension
- "destination": short folder path
- "reason": one sentence explaining why

Temperature is set to 0.2 so suggestions are consistent rather than creative. The 1B model processes each file in roughly 3–8 seconds on an RTX 2050 with 4 GB VRAM — no internet required.

The file operations layer (file_operations.py) is intentionally separate from the AI layer and handles three safety concerns independently:

Collision detection — _unique_path() appends _1, _2 … rather than overwriting
Path traversal prevention — _no_traversal() resolves both paths and checks relative_to() before any move executes
Character sanitisation — strips < > : " / \ | ? * from filenames and folder names

The UI is Streamlit with st.data_editor for the review table, so users can edit the AI's suggestions inline before approving them. Nothing moves until the user explicitly clicks Apply approved changes.

Full stack:

Component	Choice
UI	Streamlit
AI runtime	Ollama (local)
AI model	Gemma 3 1B (open-weight)
PDF reading	PyMuPDF
DOCX reading	python-docx
File ops	pathlib + shutil
Tests	pytest — 15 tests, all passing

Why Does Open Innovation Matter?

A closed-API version of this tool would have a fundamental problem: to organize your files, it would need to read your files. That means your electricity bills, your resume, your medical documents, your contracts — all uploaded to a third-party server to be processed.

With an open-weight model running locally via Ollama, none of that happens. The text extracted from your documents goes to a process running on your own GPU and never leaves your machine. There is no API key to leak, no usage bill, no terms of service that change what happens to your data next quarter.

Open innovation also made the 1B model size possible. Gemma 3 1B is small enough to run on a laptop GPU with 4 GB VRAM and still produce useful, structured output. That's only possible because Google released the weights openly — a closed-API equivalent would require a network round-trip and a paid account just to categorize a text file.

For a tool that touches personal documents, local-first isn't a nice-to-have. It's the only honest architecture.

My Agent Session

Save and embed your DevRelay session here using the agent_session tag, or remove this section.

The Lazy Payoff

I tested FolderZen on the included sample_files/ folder with 12 mixed files — PDFs, DOCXs, TXTs, an empty file, and a file with no extension.

Manual organization (rename + sort into folders by hand): ~8 minutes

FolderZen (scan → suggestions → review → apply): ~2.5 minutes

Scan: instant
AI suggestions for 12 files: ~60 seconds on RTX 2050
Review and approve: ~45 seconds
Apply + report: instant

The AI got 10 out of 12 filenames right without any editing. The two it got wrong were files with very short content (under 50 chars) — it suggested generic names instead of something specific. That's expected for a 1B model with minimal context, and the editable review table exists exactly for those cases.

The real payoff isn't the 5-minute saving on 12 files. It's that the review step forces you to look at every file before it moves — the human stays in the loop, and the AI handles the tedious part of reading and naming.

Prize Categories

🏆 Best Use of Open-Source AI
🛠️ Most Useful Developer Tool

I Built an AI Expense Tracker for Freelancers — No Cloud, No API Key, No Data Leaks

thedarkking01 — Sun, 18 Oct 2026 18:01:55 +0000

I Built FreelanceFlow: A Local-First AI Receipt Manager for Freelancers

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 2: Side Hustle

What I Built

FreelanceFlow is a privacy-first AI business assistant for freelancers. It turns a folder of scattered receipts into an organized financial dashboard — without uploading a single file to the cloud.

The problem it solves:

Every freelancer I know has the same pain: receipts scattered across email, phone photos, and random folders. At the end of the month they either spend hours manually entering everything into a spreadsheet, or they hand a mess to their accountant and hope for the best. Neither is good.

FreelanceFlow fixes this with a simple workflow:

Upload a receipt photo or PDF
AI extracts the merchant, date, amount, currency, and expense category
You review and correct before anything is saved — no blind trust in the model
Dashboard shows income, expenses, net cash flow, and category breakdowns
Invoice tracker flags unpaid and overdue invoices automatically
Monthly report generates an AI-written summary and a downloadable CSV

Who would pay for this:
Freelance developers, designers, consultants, and solo founders who hate admin work. The recurring pain is real — recording expenses, chasing invoices, and preparing records for an accountant. A Pro tier at ₹249/month (roughly $3) for higher document limits and invoice reminders is a realistic starting point to validate.

Demo

Local-first app — runs entirely on your machine.

To run it yourself:

# 1. Pull the AI model
ollama pull gemma3:4b
ollama serve

# 2. Backend
cd backend
python -m venv venv
.\venv\Scripts\activate
pip install -r requirements.txt
python seed.py        # loads sample data
uvicorn main:app --reload

# 3. Frontend
cd frontend
npm install
npm run dev

Open http://localhost:5173 — the dashboard loads with seeded sample data immediately.

What you'll see:

Dashboard with income/expense cards, a monthly bar chart, and a category pie chart
Receipts page — upload any JPG, PNG, or PDF and watch the AI fill in the form
Invoice tracker with color-coded paid / unpaid / overdue status
Reports page — pick a month, generate an AI summary, download CSV

Code

thedarkking01 / FreelanceFlow-AI-Business-Assistant

a privacy-focused AI assistant that helps freelancers manage receipts, invoices, expenses, and monthly financial reports without manually entering every transaction

FreelanceFlow — AI Business Assistant

A local-first AI receipt and expense manager for freelancers.
Upload receipts → AI extracts the details → review → track invoices → generate monthly reports.
Everything runs on your machine. No data leaves your device.

Built for the Hacktoberfest 2026 Open-Source AI Challenge.

Features

Feature	Description
Smart Receipt Scanner	Upload JPG, PNG, or PDF — OCR + Gemma extracts merchant, date, amount, category
Human-in-the-loop Review	AI suggestions are editable before saving — no blind trust in model output
AI Expense Categorization	Software, Hardware, Travel, Food, Office Supplies, Marketing, Other
Financial Dashboard	Income, expenses, net cash flow, category pie chart, monthly bar chart
Invoice Tracker	Record invoices, auto-detect overdue, mark as paid, delete
Monthly Report Generator	AI-written summary + CSV export — fallback summary if Ollama is offline
Privacy by Design	All OCR, AI inference, and storage happen locally — zero telemetry

Tech Stack

Layer

…

View on GitHub

Project structure at a glance:

freelanceflow/
├── backend/
│   ├── main.py              # FastAPI entry point
│   ├── database.py          # SQLAlchemy models
│   ├── models.py            # Pydantic validation schemas
│   ├── seed.py              # Sample data loader
│   ├── routes/
│   │   ├── receipts.py      # Upload → OCR → AI → confirm
│   │   ├── invoices.py      # Invoice CRUD + overdue detection
│   │   ├── dashboard.py     # Financial aggregations (pure Python math)
│   │   └── reports.py       # AI monthly summary + CSV export
│   └── services/
│       ├── ocr.py           # Tesseract + pdfplumber
│       ├── ai_extractor.py  # Ollama + Gemma structured extraction
│       └── categorizer.py   # Keyword-based category fallback
├── frontend/
│   └── src/
│       ├── pages/           # Dashboard, Receipts, Invoices, Reports
│       ├── components/      # Sidebar navigation
│       └── api/             # Axios client
└── tests/                   # 23 tests — validators, math, report logic

How I Built It

The AI pipeline

The core AI workflow is a three-stage pipeline:

Stage 1 — OCR

Before the AI sees anything, the document is converted to plain text. PDFs go through pdfplumber for clean text extraction. Images (JPG, PNG) go through Tesseract OCR. This keeps the pipeline debuggable — you can inspect the raw text at any point.

# services/ocr.py
def extract_text(file_path: str, content_type: str) -> str:
    if content_type == "application/pdf":
        return extract_text_from_pdf(file_path)
    return extract_text_from_image(file_path)

Stage 2 — Structured AI extraction with Gemma

The OCR text is sent to a locally running Gemma 3 4B model via Ollama. The prompt asks for a strict JSON response with defined fields — merchant, date, amount, currency, category, tax. Ollama's format: "json" parameter constrains the output to valid JSON.

# services/ai_extractor.py
response = httpx.post(
    "http://localhost:11434/api/generate",
    json={"model": "gemma3:4b", "prompt": prompt, "stream": False, "format": "json"},
    timeout=60.0,
)
data = json.loads(response.json().get("response", "{}"))

Every field is then validated and sanitized — dates are checked with date.fromisoformat(), amounts must be positive floats, categories must be from the allowed set. If Ollama is offline, the endpoint returns an empty scaffold so the user can fill it in manually.

Stage 3 — Keyword fallback categorization

If Gemma returns "Other" for the category, a keyword-based categorizer runs over the merchant name and raw OCR text as a second pass:

# services/categorizer.py
_KEYWORDS = {
    "Software": ["saas", "subscription", "adobe", "github", "aws", "hosting"],
    "Travel":   ["uber", "ola", "flight", "hotel", "airbnb"],
    "Food":     ["swiggy", "zomato", "restaurant", "cafe", "coffee"],
    # ...
}

This catches common cases even when the AI is uncertain.

Human-in-the-loop review

AI output is never saved directly. Every upload returns a pre-filled editable form. The user corrects any mistakes, then clicks "Confirm & Save." Only confirmed records enter the expense ledger. This is the most important design decision in the whole app.

Financial calculations

All arithmetic — totals, category breakdowns, net cash flow, monthly trends — is done in Python with SQLAlchemy queries. The AI is never asked to do math. This is a hard rule: AI for understanding documents, Python for numbers.

Monthly reports

The report endpoint aggregates the month's data in Python, then sends a structured prompt to Gemma asking for a 3–4 sentence professional summary. If Ollama is unavailable, a rule-based fallback generates a plain-English summary from the same numbers — so the feature always works.

Tech stack

Layer	Technology	Why
Frontend	Vite + React + TailwindCSS + Recharts	Fast dev, great charts
Backend	Python FastAPI	Async, auto-docs, Pydantic validation
AI	Ollama + Gemma 3 4B	Local inference, no API key, open-weight
OCR	Tesseract + pdfplumber	Handles both images and PDFs
Database	SQLite via SQLAlchemy	Zero config, local file, portable

Why Does Open Innovation Matter?

Three things that a closed API simply cannot give you:

1. Privacy is a real feature, not a marketing claim

When a freelancer uploads a receipt, it contains their client's name, the amount they were paid, what software they use, where they travel. With a closed cloud API, that data leaves the device. With Ollama + Gemma running locally, the receipt text never touches an external server. The only network call the app makes is to localhost:11434. That's a meaningful difference for anyone working with confidential client information.

2. It works offline and costs nothing to run

No API key. No monthly inference bill that scales with usage. No rate limits. No service going down and breaking your app. Once Gemma is pulled, the app runs indefinitely on your own hardware. For a bootstrapped side project targeting price-sensitive freelancers, this matters enormously — the marginal cost of an AI-powered feature is zero.

3. You can inspect, replace, and improve the model

With a closed API you accept whatever the provider ships. With Ollama you can swap gemma3:4b for llama3.2, mistral, or any other compatible model in one line. You can test different models against your receipt test set and pick the one that performs best for your use case. That kind of control is only possible with open-weight models.

What I Measured

I tested FreelanceFlow against a set of 20 synthetic receipts covering different formats — printed PDFs, handwritten-style images, multi-line receipts, and receipts with tax lines.

Metric	Result
Merchant name accuracy	17/20 correct (85%)
Date extraction accuracy	19/20 correct (95%)
Amount extraction accuracy	18/20 correct (90%)
Category accuracy (AI + keyword fallback)	16/20 correct (80%)
Average processing time per receipt	~4–6 seconds on CPU
Receipts needing manual correction	~25%

The 25% manual correction rate is honest and expected. The human-in-the-loop design exists precisely because the model isn't perfect. The goal isn't 100% accuracy — it's to eliminate 75–80% of manual data entry while keeping the user in control of the rest.

Failures were mostly on low-quality images (blurry phone photos) and receipts with unusual formatting. PDF extraction was consistently more reliable than image OCR.

What I Learned

Structured output prompting is worth the effort. Asking Gemma to return JSON with format: "json" and a clear field-by-field prompt description dramatically improved consistency compared to asking for free-form text and parsing it.

The fallback matters more than you think. Ollama wasn't running during one of my test sessions and the whole upload flow broke silently. Adding graceful degradation — empty scaffold for manual entry, rule-based report summary — made the app usable even without the AI layer.

OCR quality is the real bottleneck. The AI extraction is only as good as the text it receives. A blurry phone photo produces garbage OCR output, and no amount of prompt engineering fixes that. Preprocessing images (contrast, deskew) before OCR would be the highest-leverage improvement.

What's Next

Image preprocessing before OCR (contrast enhancement, deskew) to improve accuracy on phone photos
Recurring expense detection — flag when the same merchant appears every month
Invoice reminder notifications — email or desktop notification when due dates approach
Multi-currency support with exchange rate conversion for international freelancers
Export to PDF for accountant-ready monthly reports

Running the Tests

cd backend
.\venv\Scripts\activate
python -m pytest ..\tests\ -v

23 passed in 10.15s

tests/test_validators.py   — 9 tests  (Pydantic model validation)
tests/test_reports.py      — 7 tests  (month filtering, AI fallback, CSV)
tests/test_dashboard.py    — 7 tests  (expense totals, net cash flow, overdue)

devchallenge #hf26challenge #python #react #opensource

TouchGrass AI — I Built an AI Whose Only Goal Is to Get You Away From the Computer

thedarkking01 — Sat, 10 Oct 2026 16:25:05 +0000

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 1: Touch Grass

What I Built

TouchGrass AI is an open-source AI experiment designed to solve an unusual problem: getting people to stop using AI and go outside.

You tell it three things — how much time you have, your energy level, and what you're into. Gemma generates a personalized outdoor mission and sends you out the door. When you come back, you reflect on what you found.

The core loop:

The screen is intentionally the shortest part of the experience. No feeds, no notifications, no reason to stay. Just a mission and a door.

It's for anyone who spends too much time on a screen — which, if you're reading this, is probably you.

Demo

The app has 4 screens:

Step	What happens
1. Preferences	Pick your time (15m → 2h+), energy (Low/Medium/High), and interest (Nature, Fitness, Explore, Photo, Surprise)
2. AI Mission	Gemma generates a title, one-sentence scene-setter, and 3 specific tasks
3. Go outside	A minimal screen that just says: go
4. Reflect	Two text fields — what did you find, how did it go

🔗 GitHub: https://github.com/thedarkking01/TouchGrass-AI

Code

thedarkking01 / TouchGrass-AI

an AI that gives you a small outdoor mission based on your available time, energy, interests, and environment.

🌱 TouchGrass AI

An open-source AI experiment designed to solve an unusual problem: getting people to stop using AI and go outside.

Built for the Hacktoberfest Open-Source AI Challenge: Week 1 — Theme: Touch Grass 🌿

What is it?

TouchGrass AI generates personalized outdoor missions using an open-weight AI model. You tell it how much time you have, your energy level, and what you're into — it gives you a mission and sends you outside.

The core loop:

Tell TouchGrass what you have
        ↓
   AI creates a mission
        ↓
    Go outside
        ↓
  Come back & reflect

The goal is for the screen to be the shortest part of the experience.

Demo

Step	Screen
1. Pick your preferences	Time · Energy · Interest
2. Get your AI mission	Title · Description · 3 tasks
3. Go outside	Timer screen
4. Come back & reflect	Journal your adventure

Tech Stack

Layer	Tech

…

View on GitHub

How I Built It

Stack:

Frontend: React + Vite — 4 screens, no router, minimal state
Backend: FastAPI (Python) — one POST endpoint /generate-mission
AI: Gemma via Google AI Studio (free tier)
Model: gemini-3.8-flash (Gemma family, open-weight)

The AI prompt is the core of the project — a structured prompt that tells the model exactly what JSON format to return:


python
PROMPT_TEMPLATE = """
You are TouchGrass AI. Your only job is to get people off their screens and outside.

Generate a personalized outdoor mission for someone with these preferences:
- Available time: {time}
- Energy level: {energy}
- Interest: {interest}

Respond ONLY with a valid JSON object in this exact format:
{
  "title": "short catchy mission name",
  "description": "one sentence setting the scene",
  "tasks": ["task 1", "task 2", "task 3"]
}
"""

Stop Copy-Pasting Fixes: I Built DebugCoach for a Friend Learning to Code

thedarkking01 — Sun, 04 Oct 2026 16:52:12 +0000

This is a submission for the Hacktoberfest Weekend Challenge: Build for a Friend

What I Built

My friend has been learning to code for about six months. Whenever he hit an error, he would paste it into an AI chatbot, copy the corrected code, and move on.

The problem: the code was fixed, but he wasn't always learning how to debug it himself.

So I built DebugCoach, an AI debugging tutor that teaches instead of immediately giving away the answer.

DebugCoach takes a user's code and error message and guides them through a progressive hint system:

ERROR
  ↓
HINT 1
  ↓
THINK
  ↓
HINT 2
  ↓
THINK
  ↓
HINT 3
  ↓
TRY
  ↓
SOLUTION

The first hint is conceptual and spoiler-free. Each additional hint gets more specific. Only after the full hint progression does DebugCoach reveal the complete solution, explain the mistake, identify the underlying concept, and provide a practice question.

For example, take this off-by-one error:

numbers = [10, 20, 30]

for i in range(len(numbers)):
    print(numbers[i + 1])

Instead of immediately fixing i + 1, DebugCoach progressively guides the learner toward realizing that index 3 doesn't exist.

I built this specifically for my friend because I wanted to solve a real problem I had watched him experience: using AI to fix bugs without understanding why they happened.

Demo

🎥 Demo: [https://youtu.be/VWFA8CnQMMQ]

The demo shows the complete DebugCoach experience, from submitting broken code to receiving progressive hints and finally seeing the solution.

Code

thedarkking01 / DebugCoach

🐛 DebugCoach

An AI debugging tutor that helps you fix your code — without immediately giving you the answer.

Most AI tools hand you the solution the moment you paste an error. DebugCoach doesn't. It guides you through progressive hints so you actually understand what went wrong.

Paste Code + Error
       ↓
   💡 Hint 1  →  think
       ↓
   💡 Hint 2  →  think harder
       ↓
   💡 Hint 3  →  almost there
       ↓
   🎓 Solution + Explanation + Practice Question

Built for the Hacktoberfest Weekend Challenge 2026.

Tech Stack

Layer	Technology
Frontend	React 19, Vite
Backend	Python, FastAPI, Pydantic
AI	Open-weight model (Llama 3 / Mistral via Groq)
Dev tooling	Amazon Q Developer

Project Structure

DebugCoach/
├── backend/
│   ├── main.py          # FastAPI app, CORS, /analyze endpoint
│   ├── ai_service.py    # Model calls, JSON parsing
│   ├── prompts.py       # Hint level prompts + solution prompt
│   ├── schemas.py       # Pydantic

…

View on GitHub

The repository contains the complete React frontend and FastAPI backend.

Project structure:

DebugCoach/
├── backend/
│   ├── main.py
│   ├── ai_service.py
│   ├── prompts.py
│   ├── schemas.py
│   └── requirements.txt
│
└── frontend/
    └── src/
        ├── components/
        │   ├── HintCard.jsx
        │   ├── SolutionCard.jsx
        │   └── ProgressBar.jsx
        ├── App.jsx
        ├── api.js
        └── App.css

How I Built It

DebugCoach is built around an open-weight model, Qwen 3, served through Groq.

Frontend: React 19 + Vite
Backend: Python + FastAPI
Validation: Pydantic
AI: Qwen 3 (open-weight) via Groq
Coding agent: Amazon Q Developer

The core AI integration lives in backend/ai_service.py. The hint engine uses a different prompt depending on the hint level:

Hint 1 (Conceptual): Explains the general concept without giving away the answer.
Hint 2 (More Specific): Can reference variables, loops, boundaries, or other relevant parts of the code.
Hint 3 (Almost the Answer): Points toward the exact expression or line causing the problem without giving the corrected code.
Final Solution: The user can then reveal the complete solution, including the underlying concept, what went wrong, corrected code, an explanation, and a practice question.

The model returns structured JSON so the React frontend can reliably decide whether to show another hint or the final solution:

{
  "hint": "Think about the largest valid index.",
  "question": "What happens when i reaches the last position?",
  "concept": "Off-by-one error",
  "hint_level": 1,
  "is_final": false
}

The architecture is intentionally simple:

React
  ↓
FastAPI
  ↓
Hint Engine
  ↓
Qwen 3
  ↓
Structured debugging response

I also used Amazon Q Developer during development to help scaffold the FastAPI backend, build React components, work with Pydantic schemas, and debug issues such as CORS and model-response parsing.

Why Does Open Innovation Matter?

I chose an open-weight model because it powers the core tutoring experience. Here is what that makes possible that a closed API wouldn't.

1. Privacy

Users paste source code into DebugCoach. That code could come from a personal project, a university assignment, or other work they don't want to send to a proprietary AI system.

Because the model is open-weight, DebugCoach can be adapted to run locally with a tool such as Ollama, so the entire AI experience can run on the user's own machine:

React
  ↓
FastAPI
  ↓
Local inference
  ↓
Open-weight model

The user's code can stay on their computer.

2. The Model Is Swappable

I isolated the AI integration inside ai_service.py. The frontend, API, schemas, and hint engine don't need to know which model is being used.

That means I can experiment with different open-weight models without rebuilding the application, and the project isn't tied to a single proprietary provider.

3. The Model Can Be Customized

Because the model is open-weight, there's room for future experimentation. A future version of DebugCoach could be tuned specifically for beginner programmers and debugging pedagogy, getting better at:

Giving progressive hints
Explaining common programming mistakes
Teaching debugging concepts
Adjusting explanations for beginners
Supporting additional programming languages

The model isn't just an API I consume. It's something I can experiment with, replace, run locally, and potentially customize.

My Agent Session

Here's what a DebugCoach session looks like for the off-by-one example. This is an illustrative walkthrough of how the hint flow plays out:

numbers = [10, 20, 30]

for i in range(len(numbers)):
    print(numbers[i + 1])

Error: IndexError: list index out of range

Hint 1 (Conceptual): Think about the largest valid index in a list. How does counting positions in a list start?

Think: The learner pauses and tries to work out what the valid indexes are.

Hint 2 (More Specific): Look at your loop. What is the last value i takes, and what does i + 1 become at that point?

Think: The learner traces the loop by hand.

Hint 3 (Almost the Answer): The problem is in the expression inside print(). At the final iteration, it asks for an index that doesn't exist.

Try: The learner attempts the fix on their own.

Solution: DebugCoach reveals the corrected code, explains why numbers[3] fails on a 3-item list, names the concept (off-by-one error), and gives a practice question to reinforce it.

The goal is that the learner finds the bug themselves, with the answer as a last step rather than the first.