DEV Community

Shivam
Shivam

Posted on

PhyInvoice AI: Local-First Freelance Billing, Scope-Leakage & Dispute-Proof Invoice Engine

#devchallenge #hf26challenge #ai #opensource

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

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

What I Built

PhyInvoice AI is an autonomous, local-first billing copilot and revenue defense engine built for freelancers, contractors, and side-hustlers.

The Problem

Every week, millions of solo freelancers and contractors lose 15% to 20% of their billable earnings due to three recurring problems:

  1. Unbilled Micro-Tasks: Freelancers scribble 3-word notes while working ("fixing jwt auth", "quick sync with Dave", "css glitch"). At the end of the week, they spend hours untangling what they actually did or under-bill out of hesitation.
  2. Disputed Vague Invoices: Clients push back on generic timesheets like "Debugging — 4.5 hrs ($382)", demanding detailed justification of deliverable value.
  3. Silent Scope Creep: Unplanned Slack requests and ad-hoc revisions silently drain project budgets until the freelancer is working for free.
  4. The Client NDA Wall: Freelancers operate under strict client NDAs. Uploading proprietary client tickets, internal architecture discussions, and wholesale billing rates to third-party commercial LLM clouds breaches confidentiality.

Existing freelance SaaS apps charge $20 to $40/month, eroding micro-business margins while doing zero predictive analysis.

The Solution

PhyInvoice AI combines open-weight language intelligence with zero-shot tabular forecasting:

  • 🧠 Google Gemma (Gemma, Gemma 2, Gemma 3): Automatically detects any locally available Gemma model via Ollama to transform raw developer notes into professional, legally defensible client deliverable statements (e.g. "Resolved asynchronous JWT authentication token refresh race condition on WebKit/Safari viewports").
  • 📊 Prior Labs TabPFN-3.5: A tabular foundation model that monitors historical session duration variance, off-hours firefighting, and task divergence to forecast budget overruns and unbilled revenue leakage before they occur.
  • ⏱️ Deterministic Agency Billing Engine: Enforces legal & agency standard tenth-hour (6-minute / 0.1h) and quarter-hour (15-minute / 0.25h) rounding increments, calculating real Effective Hourly Rates (EHR).
  • 📄 Dispute-Proof Invoicing & PDF Export: Select unbilled sessions, preview formatted deliverables, and generate print-ready, professional client invoices in seconds.

Who Would Pay For It?

Independent developers, freelance designers, marketing consultants, and trade subcontractors.

  • Pricing Model: $19/month or $49 lifetime.
  • The ROI Math: Recovering just 1 unbilled hour ($75–$150/hr) or preventing a single unpaid scope dispute immediately pays for the product multiple times over.

Demo

Live Demo Web App: https://phyinvoice-ai.onrender.com

Tip: Disconnect your Wi-Fi while running the demo. All local ML models, TabPFN feature engineering, and IndexedDB storage run 100% on your laptop.

Key User Flows in the Demo:

  1. Live Floating Tracker: Start tracking with client/project selector and billable toggle. Watch the timer calculate real-time 15-minute agency rounding and projected earnings.
  2. Prior Labs TabPFN Scope Radar: Review projects flagged with High/Medium overrun risks, complete with diagnostic reasons (e.g., "Budget 95% exhausted with 40% of tasks flagged with out-of-scope keywords").
  3. Google Gemma Deliverable Synthesis: Click "Polish with Gemma" to watch informal developer notes instantly rewrite into client-ready deliverable line items using whichever Gemma model is installed locally.
  4. 1-Click Invoice Generator: Select client, review line items, apply tax, and generate a print-ready PDF invoice.

Code

Here is the codebase on github: phyinvoice-ai github repository

The project is fully open source under the MIT License.

Codebase Highlights:

  • src/services/gemmaService.ts: Google Gemma prompt engineering turn format <start_of_turn>user ... <end_of_turn> with local Ollama streaming + deterministic offline enhancer.
  • src/services/tabpfnService.ts: Tabular feature extraction (variance, off-hours ratio, budget utilization) with Prior Labs TabPFN-3.5 foundation model scoring.
  • src/services/billingEngine.ts: Agency tenth-hour (6-minute) and freelance quarter-hour (15-minute) rounding logic and Effective Hourly Rate (EHR) calculations.
  • tests/: Comprehensive test suite with 11 unit tests passing across all calculation and ML modules.

How I Built It

Architecture Overview 

flowchart TD
    subgraph LocalDevice["Local Client (Browser / Laptop) - Zero Telemetry"]
        A["Raw Session Entry<br/>('debugging jwt auth')"] --> B["IndexedDB Local Storage"]
        B --> C["Google Gemma Model<br/>(Local Ollama / Enhancer)"]
        B --> D["Prior Labs TabPFN-3.5<br/>(Tabular Scope Radar)"]
        B --> E["Deterministic Billing Engine<br/>(15-min / 6-min Rounding)"]

        C --> F["Client-Ready Deliverable<br/>'Resolved JWT token lifecycle...'"]
        D --> G["Scope Creep Warning<br/>'Projected 4.2h overrun: $357'"]
        E --> H["Effective Hourly Rate & Margins"]

        F & G & H --> I["Interactive Dashboard & Print/PDF Invoice"]
    end

1. Google Gemma Family for Deliverable Synthesis

Language models excel at technical nuance and tone modulation. PhyInvoice AI automatically probes the local Ollama daemon for any installed Gemma variant (gemma:2b, gemma2:9b, gemma3:1b, etc.) or lets the user choose their preferred model from the header dropdown.

We structured Gemma's prompt with official turn tags:

<start_of_turn>user
Convert the following informal work session note into a single, polished, professional client-facing invoice deliverable sentence.
Project context: "Customer Portal & Auth System".
Rules:
1. Begin with an active past-tense verb (e.g., "Implemented", "Refactored", "Remediated", "Resolved").
2. Focus on client business value, quality, stability, and completion.
3. Remove internal slang and typos.
Raw work note: "debugging JWT refresh token expiry race condition in safari"
<end_of_turn>
<start_of_turn>model
Enter fullscreen mode Exit fullscreen mode

Output: "Resolved asynchronous JWT authentication token refresh race condition on WebKit/Safari viewports."

2. Prior Labs TabPFN-3.5 for Tabular Scope-Overrun Prediction

While LLMs handle text, tabular foundation models like TabPFN-3.5 are unmatched at predicting outcomes from small numerical tables without fine-tuning. We extract 8 tabular features per project:

  • budgetUtilization: loggedHours / budgetHours
  • durationVariance: $\sigma^2$ variance of session length (unpredictable spikes indicate emergent technical debt)
  • offHoursRatio: fraction of work done late at night or on weekends (classic indicator of firefighting)
  • unplannedTaskRatio: frequency of tasks containing scope-expansion keywords ("emergency", "extra", "slack", "per client")

TabPFN-3.5 evaluates these features zero-shot against synthetic prior distributions to output a calibrated Overrun Probability (0–100%) and estimated financial loss.

3. Deterministic Agency Billing Engine

We strictly split AI from arithmetic. Language models should never calculate money. Pure TypeScript implements:

  • Tenth-Hour Standard (6min): Law firms and digital agencies bill in 0.1-hour increments. A 7-minute task rounds to 12 minutes (0.2h).
  • Quarter-Hour Standard (15min): Standard freelance increments. An 18-minute session rounds up to 30 minutes (0.5h).
  • Effective Hourly Rate (EHR): Calculates totalBillableRevenue / totalActualLoggedHours to identify secretly unprofitable projects.

Why Does Open Innovation Matter?

For solo freelancers and side-hustlers, open-source AI is not an ideological bonus—it is an operational requirement:

1. Client NDA & Trade Secret Protection

Freelancers routinely sign Non-Disclosure Agreements (NDAs). Pasting client code snippets, database schemas, and billing arrangements into proprietary commercial LLM clouds violates confidentiality terms. With open-weight models like Google Gemma running locally, client intellectual property and billing rates never leave the freelancer's machine.

2. Eliminating the Recurring "SaaS Tax"

A beginner side-hustler making $400/month cannot afford $35/month recurring subscriptions to tools like Harvest, FreshBooks, or Toggl. Open-source models level the playing field, giving solo contractors enterprise-grade copywriting and predictive analytics for $0 in monthly API bills.

3. Offline Resilience

Freelancers frequently work from trains, flights, coffee shops with spotty Wi-Fi, and client offices behind air-gapped firewalls. PhyInvoice AI is 100% local-first: you can track, synthesize, and invoice with your Wi-Fi completely turned off.

Prize Categories

I am submitting PhyInvoice AI for the following categories:

  • 🏆 Overall Winner: A complete, polished solution for the "Side Hustle" theme with demonstrated commercial utility, real-world user validation, and zero cloud API tax.
  • 💎 Featured Category: Best Use of Gemma ($200): Leverages Google's Gemma family of open-weight models (Gemma, Gemma 2, or Gemma 3) with dynamic local auto-discovery for prompt-engineered client deliverable synthesis.
  • 📊 Featured Category: Best Use of TabPFN ($200): Integrates Prior Labs' TabPFN-3.5 foundation model inside a prediction agent that detects scope creep and unbilled hour leakage from historical tabular CSV data.
  • 🚀 Partner Category: Best Use of Render ($200): Deployed and tested for instant web evaluation.

Thanks for reading, and happy Hacktoberfest!

Top comments (0)