DEV Community: Awej Pathan

ReceiptSage: A Local-First AI Receipt Organizer for Freelancers & Creators

Awej Pathan — Mon, 19 Oct 2026 19:13:03 +0000

What I Built

ReceiptSage is a local-first receipt and invoice organizer engineered specifically for freelancers, independent creators, side-hustlers, and small business owners.

Freelancers frequently handle a chaotic avalanche of PDF receipts, phone photos, and digital invoices for cloud infrastructure, domain renewals, coffee client meetings, and office equipment. Existing accounting software creates an unnecessary dilemma:

Manual Entry: Hours spent doing tedious, error-prone data entry in spreadsheets.
Cloud SaaS Platforms: High recurring fees ($15–$35/month) combined with serious privacy hazards: uploading sensitive financial documents—containing private billing addresses, tax IDs, and bank transactions—to closed cloud AI providers.

ReceiptSage solves this with open innovation:

Ingestion: Ingests pasted text, plain text files, digital PDFs (pypdf), and scanned images (pytesseract).
Open-Weight Gemma AI: Extracts structured candidate fields (Merchant, Date, Currency, Subtotal, Tax, Total, and Category) using Google's open-weight Gemma model (gemma3:1b) run locally via Ollama.
Deterministic Rule Fallback: Automatically runs a regex extraction engine if Ollama is offline or on resource-constrained devices, ensuring zero application downtime.
Math Reconciliation & Human Verification: Checks Subtotal + Tax == Total and requires user confirmation before marking records verified.
Local SQLite Persistence: Provides persistent storage in data/receiptsage.db with dual-mode support for ephemeral in-memory sessions during public demos.
Duplicate Detection: Prevents accidental double-entries using SHA-256 document hashing and content matching (merchant + date + amount).
Visual Analytics & Filters: Real-time filtering by currency, category, and month, paired with visual category spending charts.
AI Monthly Expense Summary: Generates an executive plain-language spending audit in Markdown using Gemma or statistical analytics.
Safe Exports & Backups: Exports RFC 4180 CSV with formula injection protection and creates full JSON backups with one-click restore.

Demo

Here is the end-to-end workflow:

Privacy Notice & Presets: The app opens with a clear local-first privacy notice and 4 realistic synthetic presets (Indian GST, US Cloud SaaS, European Cafe, UK Cab).
Extraction & Math Check: Click "Extract candidate fields". Gemma extracts candidate fields in seconds; an automated check validates whether Subtotal + Tax == Total.
Duplicate Detection: If the document or amount was already registered, ReceiptSage alerts the user immediately with the matching record ID.
Human Review: The user inspects and edits candidate fields, adds optional project notes, checks the confirmation box, and saves to SQLite.
Multi-Currency Register & Charts: The register displays live metric totals grouped by currency (INR, USD, EUR, GBP) and renders an expense breakdown bar chart.
AI Monthly Summary: Clicking "✨ Generate AI Expense Summary" produces a plain-language executive spending review.
Safe Exports: One-click download of spreadsheet-safe CSV (utf-8-sig with formula escaping) and JSON backup export/restore.

(All public demos use synthetic receipts; no personal or client data is ever exposed.)

Code

The complete source code is publicly available on GitHub:

👉 GitHub Repository: https://github.com/awejofficial/ReceiptSage_Starter_Repo

License: Permissive MIT License (see LICENSE).
AI Model Terms: Governed by Google's Gemma Terms of Use (see MODEL_TERMS.md).
Dev Environment: Preconfigured for GitHub Codespaces (.devcontainer/devcontainer.json).
CI/CD: Automated testing on every push and pull request via GitHub Actions (.github/workflows/tests.yml).
Cloud Deployment: Preconfigured Render Blueprint (render.yaml).

How I Built It

ReceiptSage was built in Python 3.12 with modular architecture:

1. Ingestion & Preprocessing

Digital PDF extraction via pypdf without network calls.
Image OCR via Pillow and pytesseract with graceful error handling when Tesseract is missing.
Input security: 10 MB file ceiling and 10,000-character text window.

2. Open-Weight Gemma Integration (via Ollama)

Connects to Ollama's local REST API (http://127.0.0.1:11434/api/generate) with candidate model gemma3:1b (or gemma2:2b).
Prompt injection defense: document content is enclosed inside strict boundary delimiters (--- BEGIN UNTRUSTED RECEIPT TEXT ---) with system directives ordering the model to treat text strictly as passive data.
Structured JSON output with zero temperature for deterministic reliability.

3. Resilient Deterministic Fallback

Catches network/timeout errors and seamlessly executes regular-expression rules.
Detects merchants, dates (YYYY-MM-DD, DD/MM/YYYY, DD Mon YYYY), currencies (INR, USD, EUR, GBP), subtotals, split CGST + SGST tax aggregation, and totals.
UI explicitly displays whether extraction used Gemma + rules or Rules-only fallback.

4. Pydantic Schemas & Local SQLite Persistence

Schema validation via Pydantic v2 (ReceiptFields, ExpenseRecord).
Dedicated SQLite database (data/receiptsage.db) with indices on dates, categories, and hashes.
Real-time duplicate detection based on SHA-256 source hashing and content matching.
JSON export and import for full backup/restore.

5. Automated Testing (44 Tests, 100% Pass)

A comprehensive 44-test suite verifies all features in under 3 seconds:

python -m pytest -v
# 44 passed in 2.94s
python -m compileall -q app.py src tests
# Clean compilation (Exit code 0)

Why Does Open Innovation Matter?

Open innovation—specifically open-weight AI—is transformative for solo entrepreneurs and side-hustlers:

Uncompromised Financial Privacy: Financial invoices contain banking details, tax numbers, and private residential addresses. Running open-weight Gemma on local hardware guarantees that private documents never leave the user's laptop.
Zero Marginal Operating Cost: Solo creators operating on thin margins cannot afford $20/month AI subscriptions or volatile pay-per-token API fees. Open-weight inference runs on local CPU cycles for free.
Resilience & Autonomy: Freelancers work from trains, flights, and cafes with spotty connectivity. Local open-weight AI with deterministic fallback ensures 100% uptime regardless of internet availability.
Compliance & Trust: Adheres strictly to Google's Gemma Terms of Use (April 2026), treating AI output as untrusted candidates requiring human sign-off.

Target Audience & Commercial Potential

While ReceiptSage is released as a free, open-source tool, it addresses a validated commercial market:

Target Persona: Freelancers, digital nomads, and independent consultants who submit monthly expense reports to clients or accountants.
Commercial Opportunity: A one-time purchase desktop application ($29–$49) or a packaged desktop installer (Tauri/Electron bundling the local engine) for non-technical users seeking privacy without command-line setup.

Known Limitations

Scanned PDFs: Digital PDFs with embedded text parse natively via pypdf. Image-only / scanned PDFs require conversion to PNG/JPG or local Tesseract OCR.
Hardware Latency: Local inference speed with gemma3:1b depends on the host CPU/GPU (typically 2 to 5 seconds per receipt).
Productivity Aid: ReceiptSage is an organizational productivity tool, not certified accounting software or automated tax filing.

Prize Categories

Best Use of Gemma: ReceiptSage implements Google's open-weight gemma3:1b model running locally through Ollama to parse unstructured receipts into schema-validated JSON, featuring untrusted prompt isolation, resilient fallback, and compliance with the official Gemma Terms of Use.
Best Use of GitHub Copilot / Actions: The repository features automated continuous integration via GitHub Actions (.github/workflows/tests.yml), testing dependency installation, executing the 44-test pytest suite on Ubuntu with Tesseract, and running module compilation checks on every commit.
Best Use of Render: Preconfigured with an infrastructure-as-code Render Blueprint (render.yaml) for one-click deployment of the headless Streamlit web application on Python 3.12.

![ ](https://dev-to-uploads.s3.us-east-2.amazonaws.com/uploads/articles/n3mbcj

z1ajs3bljyyx29.png)

SoilMate: Grow More, Scroll Less 🌱 — An Open-Source AI Gardening Assistant

Awej Pathan — Sun, 11 Oct 2026 09:46:06 +0000

SoilMate: Grow More, Scroll Less 🌱

An open-source AI gardening assistant built for Hacktoberfest 2026 — Week 1: Touch Grass.

The problem: When learning about gardening keeps us indoors

Imagine this.

You have a few empty pots on your balcony. You want to grow coriander, mint, or maybe some spinach. You are excited to start your first little garden.

So you pick up your phone and search for a beginner's guide.

One video leads to another. A gardening blog recommends one soil mix, a forum recommends something completely different, and suddenly you're comparing fertilizer ratios instead of planting seeds.

An hour passes. You have learned a lot about gardening, but you haven't actually started gardening.

That got me thinking: What if technology could help us spend less time learning about the outdoors and more time actually experiencing it?

That is the idea behind SoilMate.

Built for the Hacktoberfest DEV Open-Source AI Challenge — Week 1, themed Touch Grass — SoilMate turns the intention to start gardening into a practical plan of small, achievable outdoor activities.

Its guiding principle is simple:

Grow More. Scroll Less.

🌿 Introducing SoilMate

SoilMate is an AI-powered gardening companion designed to help beginners turn a small outdoor space into a starting point for growing plants.

Instead of giving users an endless conversation about gardening, the goal is to help them answer a few practical questions:

What could I grow in my available space?
How much sunlight do my plants need?
What should I do first?
What is my next gardening task?
How can I build a consistent habit of spending time outdoors?

The experience starts with a garden profile. Based on the available gardening reference data and the selected garden conditions, SoilMate helps produce a planting plan and a sequence of practical activities.

The objective isn't to keep someone chatting with AI all afternoon. It is to help them get ready, step outside, and do something with their hands.

☀️ From a garden profile to seven days of action

Gardening can feel overwhelming when you are starting from zero. SoilMate breaks the process into smaller steps.

A seven-day plan can guide a beginner through activities such as:

Day 1 — Observe your space

Spend time outside and identify where direct sunlight falls. Notice shade, wind, and the conditions around your pots.

Day 2 — Prepare your containers

Check container size, drainage holes, and the space available for roots to grow.

Day 3 — Prepare the growing medium

Inspect the potting mix and prepare it according to the requirements of the selected plants.

Day 4 — Start planting

Sow seeds or transplant suitable plants, following their spacing and depth requirements.

Day 5 — Establish a watering routine

Check soil moisture and learn to water according to the plant's needs rather than following a rigid schedule.

Day 6 — Observe and care

Look for changes in the soil and plants. Check moisture, inspect leaves, and make small adjustments where necessary.

Day 7 — Reflect and plan ahead

Record what you observed, review your progress, and decide what to do during the next week.

These activities are a starting template, not a universal planting calendar. Actual sowing, watering, and growing recommendations must reflect the selected plant and relevant local conditions.

The important part is that every step encourages a real-world action.

📵 Outdoor Mode: Your phone should get out of the way

A gardening assistant should be useful when someone is standing next to a pot, not only when they are sitting at a desk.

That is the thinking behind SoilMate's proposed Outdoor Mode.

Rather than presenting a long article or an endless AI conversation, Outdoor Mode focuses on the task that matters right now.

The design goals are straightforward:

Large, easy-to-tap controls.
High contrast for outdoor visibility.
One clear task at a time.
Short, actionable instructions.
Minimal distractions and unnecessary navigation.

The ideal interaction is simple: check the task, put the phone down, and get gardening.

Insert a genuine screenshot of Outdoor Mode here once the feature is implemented and tested.

🧠 Why open-source AI?

The open-source AI part of this project is not just a technology choice. It shapes how SoilMate can be understood, improved, and extended.

The challenge asks us to build something with open-source AI at its core and explain why open innovation matters. For SoilMate, that means making the model integration replaceable and keeping the gardening logic inspectable.

1. A model should be replaceable

AI models change quickly. A gardening assistant should not be permanently tied to one proprietary model or provider.

By keeping the inference integration separate from the recommendation engine, SoilMate can support compatible open-weight models as provider availability, quality, and cost change.

This separation also makes it easier for other developers to experiment with different models and compare their outputs.

2. Gardening facts should not depend entirely on a language model

A language model can explain information in a friendly way, but it can also produce incorrect or unsupported advice.

SoilMate's intended architecture combines curated gardening reference data with deterministic application logic and hosted AI inference.

The application can first identify suitable candidate plants using factors such as sunlight, available space, container requirements, and gardening experience. The AI can then help turn that grounded context into an understandable plan.

This separation matters: the model helps explain and organize recommendations; it should not be treated as the source of botanical truth.

3. A useful fallback matters more than a perfect demo

Hosted inference can fail. Free-tier quotas can run out, a model can become unavailable, and network requests can time out.

SoilMate is designed to provide a deterministic fallback using its available gardening data and recommendation rules.

If AI generation is unavailable, the application should communicate that limitation and offer a rule-based plan where sufficient verified data exists.

A fallback is not a claim that every recommendation is correct. Its quality still depends on the underlying reference data and rules.

4. Open innovation makes experimentation possible

An open implementation lets contributors inspect the recommendation logic, improve the data, add regional gardening knowledge, test alternative models, and challenge incorrect assumptions.

That is valuable for a project like this because local growing conditions vary, and no single model should be treated as the final authority on gardening.

Open innovation means people can understand the system, question its decisions, and help make it better.

🏗️ How SoilMate works

The intended architecture separates the gardening knowledge, recommendation logic, AI integration, and user interface.

Garden profile
      |
      v
Input validation
      |
      v
Curated gardening reference data
      |
      v
Deterministic plant ranking
      |
      v
Hosted open-weight AI
      |
      v
Structured plan validation
      |
      +---- Valid output ----> Gardening plan
      |
      +---- AI failure ------> Rule-based fallback
                                  |
                                  v
                         Outdoor tasks and journal

The project uses a Python-based web application approach, with Streamlit as the intended interface where compatible with the final implementation.

The main technical responsibilities are:

Gardening data: structured plant information and growing requirements.
Recommendation engine: transparent rules for ranking candidate plants.
AI service: hosted inference, prompt construction, response parsing, and error handling.
Validation: structured input and output validation.
User experience: the planting plan, task checklist, and outdoor-focused interface.
Testing: automated checks for data integrity, recommendation behavior, and failure handling.

The production application is intended to be accessible through a public hosted URL. AI inference therefore uses a hosted endpoint rather than requiring visitors to install a model or run a local AI server.

This has a trade-off: hosted AI requires internet access and is subject to the provider's quotas and availability. Open-weight does not automatically mean unlimited, free, or fully offline.

Insert a genuine architecture diagram or application screenshot here.

🔒 Privacy and user control

Gardening preferences do not need to become another source of unnecessary data collection.

SoilMate's intended privacy-first approach avoids requiring an account for the basic experience. Where feasible, plans and journal entries can remain in browser storage, with a JSON export and import option for users who want a backup.

That approach has limitations. Browser-stored data may not synchronize between devices, and clearing browser data can remove it.

Hosted AI also introduces a separate consideration: information included in an inference request is sent to the configured provider. The final application should explain what data is transmitted and avoid sending unnecessary personal details.

Privacy claims should reflect the actual implementation, not just the design intention.

🧪 What I want to improve next

SoilMate is a starting point for exploring a different relationship between AI and everyday life.

Some of the improvements I would prioritize are:

Better regional growing guidance based on reliable agricultural references.
More transparent explanations of why a plant was recommended.
Testing model outputs against deterministic recommendations.
Better support for different container sizes and sunlight conditions.
A simpler way to record garden observations over time.
More testing of the experience in actual outdoor conditions.

I would also like to evaluate alternative open-weight models based on recommendation quality, response time, reliability, and inference cost rather than choosing a model based only on popularity.

🌱 Try SoilMate and contribute

Source code: https://github.com/awejofficial/soilmate

Live demo: https://soilmate.streamlit.app

The repository and demo links above should be published only after they have been verified and the corresponding project is available.

If you are interested in gardening, open-source AI, or building tools that encourage people to spend more time away from their screens, there are several ways to contribute:

Improve plant data using reliable horticultural sources.
Add and test regional growing recommendations.
Improve the deterministic recommendation engine.
Evaluate compatible open-weight models.
Improve accessibility and Outdoor Mode.
Add tests for failure cases and unsupported recommendations.
Report bugs and suggest ways to make the experience more useful for beginners.

🌍 The bigger idea: AI that helps us look up

It is easy to judge an AI product by how much time people spend interacting with it.

SoilMate explores a different measure of usefulness: whether a short interaction helps someone take a meaningful action outside the screen.

Maybe that action is planting a few coriander seeds. Maybe it is observing how sunlight moves across a balcony. Maybe it is simply learning to care for one small plant.

The action itself does not need to be extraordinary.

The important thing is that technology helps make it happen.

For the Touch Grass challenge, I wanted to explore how open-weight AI, transparent application logic, and accessible gardening knowledge could work together to support that goal.

Because sometimes the best result of using AI is knowing when to put your phone down.

Grow More. Scroll Less. Happy Hacktoberfest! 🌱