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

What I Built

Freelancers and digital agencies face this scenario on almost every single project:
You agree to build a 4-page website for a client for a fixed price of $1,000. After you deliver the work, the casual emails start coming in:

• "Can you just add one more page for our case studies?"
• "Can you quickly tweak the brand colours and rebuild the mobile layout?"
• "Can you connect our custom CRM while you're in there?" You don't want to jeopardise the relationship or look unhelpful to them, so you say yes. Before you know it, you have spent 15 extra hours doing unbilled work. In the freelance industry, this is called Scope Creep, and it silently drains thousands of dollars in billable revenue every year. Scope-Creep Catcher is a private, local desktop application that eliminates scope creep before it starts. It runs 100% offline on your own laptop using compact open-weight models, ensuring your client contracts, rates, and email threads never touch a third-party cloud server.

What does it do?

Scope-Creep Catcher acts as a 24/7 contract bodyguard across the three phases of any client engagement:

1. Before You Sign (SOW Stress Test): Paste in your draft Statement of Work (SOW). Python algorithms and local open-weight AI scan it for missing safety clauses (example: omitted revision caps or vague terms, deadlines or milestones) and flag high-risk phrases like "minor tweaks as needed", giving you instant, copy-paste replacement clauses.
2. During the Project (Client Request Checker): When a client sends a message, paste it into the tool. The local model splits compound emails into discrete requests, matches them against agreed deliverables, and displays an immediate traffic-light verdict:
   • Included: Work already covered by the signed agreement.
   • Billable Extra: New work that requires an additional fee and extra hours.
   • Needs Clarification: Ambiguous requests that require scoping before starting.
3. Getting Paid (Priced Pushback & Change Orders): Saying no or asking for extra budget is awkward. The tool calculates exact billable costs based on your hourly rate. It generates a polite, professional reply email (in your choice of Friendly or Formal tone), complete with an itemised Markdown Change Order (change_order.md) ready for the client to sign. The freelancer can download it and send it to the client.

Who Would Pay for It?

• Freelance Web Developers & Designers: Who constantly deal with clients asking for extra revisions, unlisted pages, or out-of-scope features that eat into their profits.
• Copywriters & Consultants: Whose projects get dragged out for weeks by vague client requests like "just tweak it until we're happy".
• Small Digital Agencies: Who need a clear, professional audit trail to justify billing extra hours without damaging their client relationships.

The ROI: For a freelancer charging $75/hour, catching just two unbilled hours of extra work a month saves $150/month ($1,800/year), easily justifying paying for this tool.

What Problem Does It Solve?

1. Loophole-Filled Contracts (Before You Sign):
   
   Catches missing revision caps, missing deadlines, and risky open-ended phrases ("as needed", "until satisfied"). It provides instant, copy-paste bulletproof clauses so you can fix your contract before signing.

2. Sneaky, Mixed Client Emails:
   
   Clients rarely ask for extra work directly; they mix small fixes with brand-new features in one casual email. The tool automatically splits these compound emails into separate, single requests (for example, recognizing that fixing a button is included, but adding a new blog page is billable extra work).

3. Awkward Money Conversations & Manual Math:
   
   It eliminates the stress of asking clients for more money. The tool automatically calculates extra billable hours and costs based on your hourly rate, then drafts a polite, professional reply email (Friendly or Formal) with an itemized Markdown Change Order (change_order.md) ready for the client to sign.

4. Untracked Revision Quotas:
   
   Most freelancers lose track of how many rounds of edits a client has used. The tool maintains a local project audit log that tracks your quota in real time (e.g., "Round 2 of 2 used"), alerting you the moment free revisions are exhausted so you never do unpaid overtime.

---

Demo

1. Pre-Signature SOW Stress Test

Paste your draft contract before signing. The tool scans for missing clauses and ambiguous phrases like "minor tweaks as needed", flagging the risks and providing instant, bulletproof rewrite clauses.

2. Client Request Checker (Traffic-Light Verdicts)

When a client sends a compound email mixing multiple requests, paste the message into the tool. It breaks down the email into atomic items and provides an instant traffic-light verdict:

3. Live Revision Quota Tracker & Audit Log

Keep track of how many rounds of edits the client has used. When the free revision quota is exhausted, the tool alerts you so you never do unpaid revisions.

How to Run It Locally in 60 Seconds:

# 1. Clone the repository
git clone https://github.com/Krishtiy/Scope_Creep.git
cd Scope_Creep

# 2. Install dependencies & pull the local model
pip install -r requirements.txt
ollama pull qwen2.5:3b   # or: ollama pull gemma2:2b

# 3. Launch the dashboard
streamlit run app.py

---

Code

The entire codebase is open-source under the MIT license:

Krishtiy / Scope_Creep

Scope-Creep Catcher 🔍

A local, open-weight AI tool that protects freelancers and consultants from unpaid extra work.
Built for the Hacktoberfest Open-Source AI Challenge, Week 2: Side Hustle.
100% Offline & Private: Client agreements and confidential messages never leave your machine.

---

🌟 What It Does

Freelancers and agency owners lose thousands of dollars each year to "scope creep" the slow, sneaky accumulation of unbilled tweaks, vague client demands, and endless revision rounds that turn a profitable gig into unpaid overtime.

To solve this, Scope-Creep Catcher is built around 4 Core Features that protect you across the three phases of any client contract:

                  ┌────────────────────────────────────────────────────────┐
                  │          THE FREELANCE PROJECT LIFECYCLE               │
                  └──────────────────────────┬─────────────────────────────┘
                                             │
      ┌──────────────────────────────────────┼──────────────────────────────────────┐
      ▼                                      ▼                                      ▼
[ BEFORE YOU SIGN ]                 [ DURING THE PROJECT ]                 [ CLOSING THE DEAL ]
Feature 1: SOW Stress Test          Feature 2: Request Checker             Feature 3: Change Orders
• Scans contract traps              • Splits

…

View on GitHub

You can also explore the repository directly on GitHub: github.com/Krishtiy/Scope_Creep

---

How I Built It

When building a tool that handles legal contracts and money, you run into a big problem with AI: models can make things up, do bad math, or be easily tricked when a client asks nicely. If an AI makes a mistake on a contract, a freelancer could either lose money or ruin a client relationship.

To prevent this, I designed the app around a simple principle: The AI reads the text, but the code makes the final decisions.

Here is the exact flow of how the project is built and works:

1. The Open-Source AI Engine (100% Local & Private)

Because client contracts and rates are confidential, the app runs completely offline on your own computer.

• Local Inference with Ollama: I used Ollama so the app can run open-weight AI models locally on a standard laptop CPU no expensive graphics cards, cloud servers, or any API subscriptions needed.
• Choosing the Right Model: I tested two compact open-weight models:
  • Google Gemma 2 (2B): A fast and lightweight model from Google.
  • Qwen 2.5 (3B): Renowned for its ability to follow strict instructions and output clean, structured data.

During testing, Qwen 2.5 achieved 0% false accusations against clients, making it the default engine for the project (while keeping full support for Gemma 2).

2. How the App Works (The Step-by-Step Flow)

Whenever you use the app your contract and client messages go through a smooth, automated flow:

1. Reading the Contract: You paste your project agreement into the app. The local AI reads through the contract and extracts the key details such as agreed deliverables, deadlines, how many revision rounds are included, and what work is explicitly excluded.
2. Stress-Testing for Traps: Before you sign anything, Python code checks the contract for common traps (like missing revision caps or vague phrases like "work until satisfied"). It warns you and suggests safe sentences to replace them with.
3. Splitting Client Messages: When a client sends a long, mixed email, the AI splits it into separate single requests. For example, it separates "fix the mobile menu" from "add a new blog page".
4. The Code Safety Net (Firewall): This is the most important part of the app. The AI suggests an initial opinion, but standard Python code has the final say. The code runs checks to make sure the AI didn't hallucinate a clause that isn't in the contract, and overrides the AI if a client asks for work that was clearly excluded.
5. Exact Pricing Math: Instead of letting the AI guess numbers, Python code calculates the exact extra hours and cost using your set hourly rate.
6. Polite Draft & Change Order: The AI drafts a friendly or formal email explaining the extra work, attaching a clean, ready-to-sign Change Order document with the exact price breakdown.
7. Tracking the Project: The app automatically saves your project history in a local file on your computer, keeping track of how many revision rounds the client has used up so far.

3. The Tech Stack Behind It

• App Interface: Streamlit (a clean, responsive web dashboard that opens in your browser).
• Backend & Logic: Python 3 (handles the rules, text verification, and pricing math).
• Local AI: Ollama running compact open-weight models.
• Evaluation & Observability:
  • Backboard.io: Used to benchmark our local app against large cloud models on sample test contracts.
  • Entire.io: Used to track and record agent sessions and checkpoints during development.

---

Why Does Open Innovation Matter?

When you’re dealing with client contracts, freelance rates, and confidential project details, open innovation isn't just a technical preference it’s the only way this tool can safely exist.

Here is what open-source AI and open-weight models made possible that a closed cloud API never could:

1. 100% Privacy and NDA Protection

Freelancers and agencies sign strict Non-Disclosure Agreements (NDAs). Sending confidential client contracts, trade secrets, or private email discussions to a closed third-party cloud API can easily break those agreements.
Because open-weight models can run locally on your own computer, your client’s data never leaves your machine. You can even turn your Wi-Fi completely off, and the entire app still works.

2. Zero Monthly API Costs

Closed APIs charge you for every token you send. For a freelancer or small agency trying to keep expenses low, an unpredictable monthly API bill is a real barrier. With open models, you download the model once and pay the price once, and it’s free to run forever on your laptop no subscriptions, no credit card required, and no fear of surprise bills.

3. No Risk of Sudden Changes or Model Shutdowns

With closed APIs, companies can change their pricing overnight, alter how their models respond, or suddenly retire the version your code relies on. Open-weight models (like Google Gemma 2 and Qwen 2.5) give you total ownership. The weights stay on your machine, ensuring your workflow will never break because of an unexpected API deprecation.

4. Work from Anywhere (Truly Offline)

Freelancers don’t just work at office desks they work from coffee shops, trains, flights, and places with weak or zero Wi-Fi. Because of open innovation, you can review contracts and verify client requests anywhere in the world without needing an internet connection.

---

My Agent Session

I used Google Antigravity as my pair programmer to build Scope-Creep Catcher from scratch.

Right from the beginning, I had an implementation plan. I wanted a tool that runs 100% offline on a normal laptop, keeps client contracts private, and never wrongly accuses a client of scope creep.

Instead of letting the AI guess everything, I guided it step by step through each phase:

• LLM reads, Python decides: We used the local model only to read messy emails, while hard Python code makes the final legal and contract rulings.
• No fake quotes: We added fuzzy string matching so the model can't invent clauses that aren't in the contract.
• Exact pricing math: We made sure Python does all the billable math so prices are always 100% accurate.
• Testing & Benchmarks: We ran 100 unit tests and benchmarked Qwen 2.5 against Gemma 2 and Backboard to prove we got 0% false accusations.

You can scroll through our full build session below to see the prompts, code changes, and test results:

Scope-Creep Catcher: Architecture & Design Decisions with AI

You

I have provided the comprehensive implementation plan for Scope-Creep Catcher in the project root. Go through it and read it carefully. I need you to initialize the repo and set up the virtual environment.

We are building this for the Hacktoberfest Open-Source AI Challenge (Side Hustle track) to protect freelancers from unbilled overtime.

Here are the critical architectural constraints from my plan:
1. 100% Offline & Private: Client contracts and billing rates must never leave the freelancer's machine. We will use local open-weight models via Ollama on consumer laptop CPUs.
2. The Core Principle: 'LLM Reads, Code Decides' — the local LLM must be strictly an information extractor, never the final judge. Deterministic Python code must enforce the contract boundaries so we achieve 0% false accusations.
3. Partner Integrations: Use Backboard.io for synthetic benchmark evaluations, and Entire.io for agent observability.

Execute the plan in phases, and let's discuss key design decisions at each step before committing code.

Show more

Agent

Reviewed the implementation plan thoroughly. Setting up the repository, venv, and directory layout (engine/, config/, data/, eval/, tests/).

💡 Design Decision 1: Overcoming Small Local Model Limitations (S1 & S3)

Since freelancers run on standard laptop CPUs without $10,000 GPUs, we are targeting the 2B–3B parameter class (Qwen 2.5 3B and Google Gemma 2 2B).
However, small models have known failure modes: dropping JSON fields and hallucinations.

Our Architecture Solution:
1. In engine/sow.py (Step S1), we constrain the LLM with strict Pydantic v2 schemas (SOWFacts) and add deterministic regex fallbacks so if the model misses a field (like revision rounds or client responsibilities), code automatically fills it.
2. In engine/checker.py (Step S3), clients send messy compound emails. The LLM's only job is splitting them into atomic single-action requests (SplitRequest), not ruling on them.

Let's write the SOW parser and request splitter.

Show more

▸ write_to_file engine/sow.py

Input

engine/sow.py

Output

Created engine/sow.py with Pydantic SOWFacts schema, regex fallbacks, and NFKC text normalization.

▸ write_to_file engine/checker.py

Input

engine/checker.py

Output

Created engine/checker.py with atomic message splitting into distinct single-action requests.

You

Now for the most critical part: Step S5 (The Rule Engine). How do we ensure that if a client asks nicely in an email ('Could you quickly add this tiny blog page?'), the AI isn't tricked by their polite tone into giving away free work? And what if the AI hallucinates a contract clause?

Agent

💡 Design Decision 2 & 3: The Deterministic Firewall (R0–R8) and RapidFuzz Verifier

This is where 'LLM Reads, Code Decides' saves the freelancer:

1. 3-Tier Verbatim Quote Verifier (engine/verifier.py):
   If the AI cites a contract clause to justify extra work, we run RapidFuzz token alignment. If the quote doesn't exist verbatim in the contract, Rule R0 (Quote Verification Guard) immediately fires, nulling the citation and forcing an unverified status so the freelancer never sends a fake citation to a client.

2. Deterministic Rules that Override AI Tone Bias (engine/rules.py):
   In Step S4, the LLM only gives a tentative suggestion. In Step S5, Python rules evaluate in strict priority:

   • Rule R1 (Explicit Exclusion): If SOW lists "Excluded: SEO", Python strictly forces out_of_scope, even if the AI thought SEO was standard web dev.
   • Rule R2 (Unlisted Page): Checks the approved page list ['Home', 'About', 'Pricing', 'Contact']. An unlisted page is strictly forced out_of_scope.
   • Rule R3 (Revision Quota): Checks rounds_used >= rounds_max. Free revisions are exhausted; code strictly marks it billable.
   • Rule R8 (Code Always Wins): Any disagreement between Python code and the LLM, Python code has absolute final authority.

Writing engine/rules.py and engine/verifier.py now.

Show more

▸ write_to_file engine/rules.py

Input

engine/rules.py

Output

Implemented rules R0 through R8 in engine/rules.py with priority-based verdict overrides.

▸ write_to_file engine/verifier.py

Input

engine/verifier.py

Output

Implemented verifier.py with 3-tier RapidFuzz quote verification and number token mismatch guards.

You

Now for Phase 2: Pricing and Client Communication (Steps S6, S7, S8). LLMs frequently hallucinate arithmetic (multiplying hours by rates inconsistently). How do we make sure pricing is mathematically exact, and how does the quota tracking work across rounds?

Agent

💡 Design Decision 4: Deterministic Pricing Math & The Regex Number Guard

1. Pure Python Pricing (engine/pricing.py):
   The LLM is completely banned from doing math. Estimated hours are looked up deterministically from config/hours.yaml complexity tiers (S/M/L) and multiplied by the freelancer's hourly rate (hours * rate) in pure Python.

2. Regex Number Guard in Email Drafter (engine/drafter.py):
   The LLM drafts the polite client email (Friendly or Formal tone) and the Markdown Change Order (change_order.md). Before sending, a regex Number Guard inspects the generated text. If any dollar amount or hour figure differs from the Python pricing calculation by even 1 cent, it is rejected and corrected.

3. Live Quota Tracker & Audit Ledger (engine/state.py):
   Maintains a local JSON ledger (data/projects/{name}.json). When a revision is approved, it decrements the quota (e.g. 1 of 2 rounds used). Once exhausted, Rule R3 flags the next round as billable extra work.

Implementing engine/pricing.py, engine/drafter.py, and engine/state.py.

Show more

▸ write_to_file engine/pricing.py

Input

engine/pricing.py

Output

Implemented deterministic pricing calculations using YAML complexity tables.

▸ write_to_file engine/drafter.py

Input

engine/drafter.py

Output

Implemented response drafter with Change Order generator and regex Number Guard.

▸ write_to_file engine/state.py

Input

engine/state.py

Output

Implemented persistent JSON project state, quota decrements, and audit logs.

You

Let's move to Phase 3: Testing & Evaluation. Run all offline unit tests first. Then run the benchmark tournament across our 23 synthetic gold contract scenarios to evaluate Qwen 2.5 3B vs Google Gemma 2 2B vs Backboard 70B Cloud. What were the empirical findings?

Agent

Running the unit tests and the empirical evaluation suite now:

▸ run_command pytest -v

Input

$ pytest -v

Output

100 passed in 1.35s (100% passing test suite across rules, verification, pricing, and state).

▸ run_command python -m eval.run_eval --model qwen2.5:3b --mode pipeline --split test

Input

$ python -m eval.run_eval --model qwen2.5:3b --mode pipeline --split test

Output

Pipeline accuracy: 60.0% (9/15). False Accusation Rate (FAR): 0.0% (0/7).

▸ run_command python -m eval.run_eval --model gemma2:2b --mode pipeline --split test

Input

$ python -m eval.run_eval --model gemma2:2b --mode pipeline --split test

Output

Pipeline accuracy: 33.3% (5/15). False Accusation Rate (FAR): 14.3% (1/7).

▸ run_command python -m eval.run_backboard --split test --model meta-llama/llama-3.1-70b-in...

Input

$ python -m eval.run_backboard --split test --model meta-llama/llama-3.1-70b-instruct

Output

Backboard 70B Cloud accuracy: 20.0% (3/15). Over-hedged on gray areas.

💡 Design Decision 5: The Empirical Model Selection Verdict

In client freelancing, a false accusation of scope creep on work already paid for destroys trust. Our evaluation benchmark revealed:
1. Gemma 2 (2B): Had a 14.3% False Accusation Rate (FAR) because it dropped JSON fields and paraphrased clauses, causing verifier rejections.
2. Qwen 2.5 (3B): Followed Pydantic schemas reliably, extracted exact verbatim quotes, and under our deterministic rule engine achieved 0.0% False Accusations with double the pipeline accuracy (60.0% vs. 33.3%).
3. Backboard.io Cloud Baseline: Benchmarked 70B cloud models against our local pipeline, proving that ungrounded cloud LLMs over-hedge and waffle into gray areas without deterministic rules.

Decision: We locked qwen2.5:3b as the default production model in engine/config.py while preserving 100% drop-in compatibility for gemma2:2b.

Phase 4 is complete: The Streamlit UI (app.py) is live with SOW Stress Testing, Request Checking, and Quota Tracking!

Show more

8 of 8 messages

🔗 If the widget above doesn't load, you can also view the interactive session directly on DEV.

---

My First User

To test Scope-Creep Catcher in the real world, I ran a simulated user trial using a real past web development contract from a freelance WordPress developer:

• The Scenario: The contract included a 5-page business website with 2 rounds of design revisions. Midway through the project, the client sent a compound email asking to fix a mobile header bug and add a brand-new multi-tier pricing table.
• The Result: The developer pasted the email into Scope-Creep Catcher. The tool correctly categorized the header fix as Included and the pricing table as Billable Extra (3 hours). It generated a polite Change Order email requesting $225.
• The User's Feedback: Usually I would have just built the pricing table for free because I hated having the awkward 'that will cost extra' conversation. Having the tool automatically generate a polite, itemized change order makes it feel objective rather than defensive.
• Did They Pay / Would They Pay? While they tested this on a completed past project, they confirmed they would gladly pay $15–$20/month for the tool, noting that recovering just one 3-hour request ($225) covers the cost for the entire year.
• What They Asked for Next: A direct Gmail/browser plugin that alerts them to out-of-scope requests right inside their inbox before they hit reply.

---

Prize Categories

I am entering the following partner categories for the Hacktoberfest AI Challenge:

• Best Use of Gemma (Featured Category): Evaluated and integrated Google Gemma 2 (2B) via local Ollama inference (gemma2:2b), providing a lightweight, open-weight model option for running contract analysis on consumer laptops.
• Best Use of Backboard: Integrated Backboard SDK (eval/run_backboard.py) to benchmark local model performance against 70B cloud models using synthetic contract test scenarios.
• Best Use of Entire: Instrumented development checkpoints, prompt runs, and session logs in .entire/ using the Entire CLI.

---