HisaabMate：以 gemma3:1b 建構本地 AI 工時記錄工具

Hacktoberfest Open-Source AI Challenge Week 2: Side Hustle Submission 💸

How I Built It

Architecture

Primary Workflow:

Paste Hinglish notes / Presets / .txt or text PDF.
Ingest & sanitize in Streamlit.
Extraction Engine: Local Ollama API + gemma3:1b JSON Schema.
Python validates dates, clients, durations & categories.
Human edits & adds/removes rows in Neobrutalist Data Editor.
North-Star Audit Tracker + Client & Category Charts.
Formula-Safe CSV Export + Client Invoice Memo.

Offline Fallback:

Deterministic Hinglish Regex Parser (ensures the app never breaks).

Tech Stack & Design Decisions

Google Gemma 3 (gemma3:1b) via Ollama: Runs locally at http://localhost:11434/api/chat. Despite its compact 1B parameter footprint (runs smoothly on consumer laptops), pairing it with Ollama's JSON Schema format constraint and explicit Hinglish few-shot conversion rules (1 ghanta = 60, aadha ghanta = 30) makes structured extraction fast and reliable.
Deterministic Offline Hinglish Fallback (extract_work_entries_offline): If Ollama is offline or zero-latency parsing is needed, the built-in regex parser extracts ISO dates, Hinglish durations, "ke liye" / "ke saath" client names, categories, and "billable nahi" flags in-process.
In-Memory Document Guardrails (src/document_parser.py): Uses pypdf and BytesIO to read uploaded .txt and text-based PDF work logs entirely in RAM, enforcing a 5 MB size cap and 30-page PDF limit without touching the filesystem.
Pastel Neobrutalist Streamlit UI (app.py): Styled with Space Grotesk, Plus Jakarta Sans, and JetBrains Mono typography, tactile 2px solid #1E293B ink borders, 4px offset shadows, and @st.cache_data helpers for instant reruns.
21 Offline Unit & Headless UI Tests (tests/): Automated tests verify schema validation, DataFrame NaN/float round-trips, formula-injection escaping, PDF guardrails, and full UI workflows offline.

Community Wisdom That Shaped the Build

While designing the local structured extraction pipeline, these DEV community posts helped shape the architecture:

Ollama Structured Outputs in Practice — Getting Type-Safe JSON from Local LLMs with Pydantic by @jangwook_kim_e31e7291ad98
LLM Structured Outputs and JSON Schema: Tool Calling That Never Drifts by @jeff_pdc
Clean JSON Extraction with Ollama and Python by @nearshi

Why Does Open Innovation Matter?

100% Client Privacy & NDA Compliance: Freelancers log work involving unreleased features and real client names. Because gemma3:1b runs locally and files are parsed strictly in RAM, zero bytes of client data ever leave the freelancer's laptop.
Zero Per-Request API Cost (Viable Side-Hustle Economics): Running an open-weight 1B model on the user's own CPU/GPU brings marginal inference cost to $0.00, allowing HisaabMate to exist as a free open-source tool or a one-time-purchase app.
No Vendor Lock-In & Bilingual Control: Closed APIs deprecate models and behave unpredictably on code-mixed languages like Hinglish. Open Python validation rules let users inspect every prompt, swap local models, or work completely offline.

My Agent Session

During development, I worked with my coding agent to:

Design the strict separation between natural-language extraction (src/ollama_client.py) and deterministic Python financial validation (src/worklog.py).
Fix a subtle Pandas/Streamlit st.data_editor round-trip bug where newly added rows introduced NaN and float durations, solved via _sanitize_editor_records().
Build the offline Hinglish fallback parser and the 21-test unittest + AppTest suite.

My First User

I tested HisaabMate on my own weekly Hinglish developer logs and shared it with a fellow student freelancer who tracks tasks in WhatsApp messages.

What happened: Pasting raw Hinglish notes immediately separated billable client tasks (BharatPay, ZeptoClone) from non-billable sprint syncs and admin work, flagging incomplete rows where details were forgotten.
What they liked most: The Audit Readiness bar and the one-click Markdown Invoice Memo, which can be pasted straight into a client WhatsApp/Slack message alongside the CSV.
Would they pay?: They wouldn't want another monthly SaaS subscription, but would gladly pay a small one-time fee for a local desktop tool that keeps client names private and recovers 2+ forgotten billable hours per sprint.

Prize Categories

Best Use of Gemma: HisaabMate uses Google's open-weight gemma3:1b model running locally via Ollama (src/ollama_client.py) as its primary extraction engine. Using JSON Schema constrained decoding (ENTRY_SCHEMA at temperature: 0), gemma3:1b parses code-mixed Hinglish and English work notes—converting phrases like "2 ghante", "aadha ghanta", and "billable nahi" into structured, schema-validated timesheet drafts without sending a single token to the cloud.