ScopeShield: A Local-First AI Agent That Turns Client Scope Creep Into Paid Change Orders (Gemma + TabPFN-3.5)

Hacktoberfest Open-Source AI Challenge Week 2: Side Hustle

What I Built

Every freelance developer and designer knows the dread of the "quick favor" message:

"Hey! Loving the staging build. Can we just add a quick role-based export button and tweak the webhook payload before Friday? Should only take 15 minutes!"

Saying yes destroys your hourly rate; saying no feels confrontational. According to freelance industry surveys, independent contractors lose 18% to 25% of their annual revenue to unbilled scope creep simply because diagnosing the contract violation, estimating the real effort, and writing a polite pushback email takes too much mental energy in the middle of a sprint.

ScopeShield is a local-first AI Contract & Change-Order Agent built specifically for independent freelancers and micro-agencies.

Instead of acting like a generic chat wrapper, ScopeShield performs a deterministic 4-stage workflow:

1. Contract Clause Auditing (Gemma 3): Ingests your signed Statement of Work (SOW) PDF and incoming client messages (Slack/Email/WhatsApp) locally, identifying the exact deliverables clause being stretched.
2. Historical Effort Forecasting (TabPFN-3.5): Looks at your CSV of past completed tickets/projects and predicts the actual hours required and schedule slip probability (because a "15-minute tweak" historically takes 4.2 hours once QA and deployment are factored in).
3. Live Market Rate Benchmarking (SerpApi): Pulls current freelance market rates and comparable specialized task pricing so you don't undercharge on the addendum.
4. Zero-Friction Change Order Generation: Outputs a polite, psychologically calibrated client response paired with a 1-click PDF Change Order addendum.

Who pays for this? Freelance full-stack developers, UI/UX designers, and boutique 2–5 person dev shops billing $40–$150/hr. Recovering just one unbilled 3-hour "quick tweak" a month pays for a $19/month tool ten times over.

Pipeline in Action

ScopeShield Dashboard Screenshot

Above: ScopeShield flagging a "minor webhook adjustment" against Section 3.2 of the original SOW, alongside TabPFN-3.5's prediction of 4.6 actual engineering hours.

Code

Core Repository Structure

scopeshield/
├── agent/                  # Mastra agent orchestration & tool definitions
│   ├── workflows/          # Multi-step SOW audit + TabPFN forecasting pipeline
│   └── tools/              # SerpApi rate lookup & PDF parser tools
├── backend/                # FastAPI inference bridge + TabPFN-3.5 client
├── frontend/               # React + Tailwind UI (hosted on Render)
├── sample_data/            # Pre-loaded historical ticket CSVs & sample SOW PDFs
└── render.yaml             # Infrastructure-as-Code for 1-click Render deployment

How I Built It

ScopeShield is architected around an open-source reasoning core combined with specialized tabular foundation models and full observability:

[Signed SOW PDF] + [Client Message]
         │
         ▼
┌─────────────────────────────────────────────────────────┐
│             Mastra Agent Orchestrator                   │
│  (Instrumented end-to-end with Sentry Agent Tracing)    │
└────────┬───────────────────────┬────────────────────────┘
         │                       │
         ▼                       ▼
┌─────────────────────┐ ┌─────────────────────────────────┐
│   Gemma (Local/vLLM)│ │  TabPFN-3.5 (Prior Labs API)    │
│ Semantic SOW diff & │ │  Reads historical_tasks.csv to  │
│ clause extraction   │ │  predict real hours & overrun % │
└────────┬────────────┘ └────────┬────────────────────────┘
         │                       │
         ▼                       ▼
┌─────────────────────────────────────────────────────────┐
│   SerpApi Live Market Benchmark                         │
│   Grounds change-order hourly pricing in live comps     │
└────────┬────────────────────────────────────────────────┘
         │
         ▼
[Polite Pushback Email + Itemized Change Order PDF]

1. Open-Weight Reasoning Core (Gemma): We use Google's open-weight Gemma model (running locally via Ollama for strict offline NDA mode, and served via containerized runtime for our public demo) to perform structured semantic comparison between the signed SOW sections and the unstructured client request. Gemma outputs strict JSON containing violated_clause_id, scope_delta_summary, and severity_score.

2. Tabular Foundation Model (TabPFN-3.5): LLMs are notoriously bad at doing regression math over historical spreadsheets. Instead of asking an LLM to guess how long a task will take, we pass the freelancer's historical_projects.csv (task category, complexity, client revision count, stack, actual vs. estimated hours) directly to Prior Labs' TabPFN-3.5. With zero training wait time, TabPFN predicts the realistic hour distribution and overrun risk.

3. Agent Harness (Mastra): Orchestrates the deterministic handoff between document parsing, Gemma's semantic extraction, SerpApi's rate check, and TabPFN's tabular inference.

4. Observability (Sentry Agent Tracing): Every tool call, prompt token count, and latency span is tracked via Sentry.

Debugging with Sentry Agent Tracing

During early testing, our end-to-end change-order generation was taking 8.4 seconds. Looking at our Sentry Agent Tracing waterfall immediately revealed the culprit.

Sentry Agent Trace Screenshot

• What we found: Our SerpApi tool was passing raw, unstripped search snippet metadata directly into Gemma's context window (burning 2,140 extra input tokens per run), and TabPFN was being called sequentially after SerpApi despite having zero dependency on it.
• The fix: We parallelized the TabPFN-3.5 and SerpApi tool calls inside our Mastra workflow and stripped the SerpApi payload down to top-5 structured rate cards. Total pipeline latency dropped from 8.4s to 2.9s (-65%), and token consumption dropped by 71%.

Why Does Open Innovation Matter?

When I talked to freelancers about why they don't paste client contracts and Slack arguments into ChatGPT or Claude, two hard blockers came up immediately: NDA Legal Liability and Unit Economics.

1. Strict NDA & Data Privacy Compliance: Standard freelance MSA/SOW contracts contain strict non-disclosure clauses prohibiting contractors from uploading proprietary architecture specs, pricing tables, and internal correspondence to third-party closed SaaS APIs that retain data. Because ScopeShield runs Gemma locally on the freelancer's laptop, confidential client PDFs never leave localhost. Open weights make this product legally usable.

2. Right-Sized Models Beat Monolithic APIs: By pairing a compact, fast open-weight language model (Gemma) for text extraction with a specialized tabular foundation model (TabPFN-3.5) for numerical hour prediction, we outperform a massive closed frontier LLM on both accuracy and cost.

Metric	Closed Frontier LLM Wrapper	ScopeShield Open Stack (Gemma + TabPFN-3.5)
NDA / Offline Compliance	Fails strict agency NDAs (cloud data retention)	100% compliant (runs locally on laptop)
Effort Estimation Method	Hallucinates numbers via text token prediction	True tabular regression on historical CSVs via TabPFN-3.5
Marginal Cost per 1,000 Audits	~$18.50 (multi-page PDF context + reasoning)	$0.00 local (or <$0.80 on self-hosted cloud)
Schema Lock-in	Vulnerable to silent model deprecations	Full weight control & fine-tunable on domain SOWs

My First User

To put the "Side Hustle" prompt to the test, I gave ScopeShield to Kumar, a freelance full-stack React/Node developer who builds MVP web portals for local businesses.

• The Real Test: He uploaded a real 4-page SOW from a current project and pasted a WhatsApp message where his client asked to "quickly add multi-branch role filtering and WhatsApp invoice alerts"—claiming it was already implied under "Dashboard Views."

• What Happened: ScopeShield pinpointed Section 2.4 (Single-Tenant Admin Scope) in 3 seconds, ran his past 40 Jira ticket exports through TabPFN-3.5, and showed him that similar "notification + role" requests previously took him 6.5 hours (not the 1 hour he was about to quote). It drafted a friendly reply offering to bundle it as a Phase 1.1 mini-addendum for ₹8,500 (~$100).

• Did they pay / Would they pay? He sent the generated reply with almost zero edits—and the client approved the paid addendum that same evening! He told me:

"Honestly, having the breakdown table showing why it's 6.5 hours based on past sprints gave me the confidence not to cave. I'd easily pay $15/month if this had a Chrome extension that sits right inside Gmail and WhatsApp Web."

• What he asked for next: A direct Razorpay/Stripe payment link generator embedded directly inside the exported Change Order PDF so clients can approve and pay the deposit in one click.

Prize Categories

• Best Use of Gemma: Uses Google's open-weight Gemma model as the core semantic contract auditor and structured JSON change-order generator.
• Best Use of TabPFN: Uses Prior Labs' TabPFN-3.5 inside our prediction agent to forecast realistic task hours and schedule overrun probabilities directly from the freelancer's historical project CSVs.
• Best Use of Render: Hosted the full-stack ScopeShield web application and FastAPI agent bridge on Render via Blueprint (render.yaml).
• Best Use of Mastra: Orchestrates the multi-step agent workflow, parallel tool execution, and state transitions across Gemma, TabPFN, and SerpApi.
• Best Use of Sentry Agent Tracing: Instrumented the agent pipeline with Sentry Agent Tracing to inspect token burn, debug sequential tool bottlenecks, and cut latency by 65%.
• Best Use of SerpApi: Grounds every generated Change Order in live freelance market rate comps fetched via SerpApi.
• Best Use of a .tech Domain: Deployed live on a .tech domain claimed via the Hacktoberfest promo.