DEV Community

Rish
Rish

Posted on

I Built an NDA-Safe Proposal Scoper That Runs Gemma on My Laptop

#devchallenge #hf26challenge #hacktoberfest #ai

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

It is 10:30 PM. A prospective enterprise client emails you a 14-page RFP under a strict mutual Non-Disclosure Agreement (NDA). They need a fixed-price proposal and a milestone plan by 9:00 AM tomorrow.

As a freelancer or boutique agency engineer, you are caught in a bad dilemma:

  1. The Dangerous Shortcut: Paste the client's confidential brief into a commercial cloud chatbot (OpenAI, Anthropic). You get a draft proposal in 30 seconds, but you may have just committed a material breach of contract by leaking proprietary product architecture or clinical data to a third-party server.
  2. The Unpaid Grind: Spend the next 5 hours manually combing through pages of ambiguous text, calculating hour ranges by hand, and praying you didn't miss that casual line on page 9 ("must be completely bug-free and scale infinitely") that will lead to three months of unpaid scope creep.

I built ScopeLock to solve this dilemma.

ScopeLock is an NDA-safe, local-first proposal scoper designed for freelance developers. It ingests client briefs (PDF, Markdown, or plaintext) entirely on your machine using open-weights Google Gemma models running in Ollama. It outputs:

  • Atomic Functional & Non-Functional Requirements, each anchored to a character-for-character verbatim quote from the brief.
  • Deterministic Pricing & Milestone Breakdown, calculated strictly in deterministic code—the language model is never allowed to perform money math or arithmetic.
  • Scope-Creep Guardrails, which flag hazardous, ambiguous client phrases and generate ready-to-paste Statement of Work (SOW) protective clauses.
  • A 'Questions Before I Quote' Email, so you can clarify critical technical unknowns before locking in a fixed bid.
  • Zero Client-Content Egress Proof, verified by an automated canary test.

Demo

(Note: In adherence to honest disclosure, the hosted showcase runs in demo mode, faithfully replaying authentic execution traces generated by local Gemma 4 without cloud inference).

Quickstart: Run It Locally in 3 Commands

ScopeLock is 100% open-source and runs offline:

# 1. Pull the model locally
ollama pull gemma4:e4b

# 2. Start the backend API
pip install -r backend/requirements.txt
uvicorn backend.main:app --port 8000

# 3. Launch the React workbench
cd frontend && npm install && npm run dev
Enter fullscreen mode Exit fullscreen mode

You can also run it directly via the CLI:

python -m backend.cli sample_brief.pdf --rate 120 --currency USD --contingency 20
Enter fullscreen mode Exit fullscreen mode

Code

The complete source code is released under the Apache-2.0 License:
👉 GitHub: Rish-51/ScopeLock

Key files in the repository:

How I Built It

1. Why 3 Small Constrained Calls Beat 1 Giant Schema

Small open-weights models (2B to 9B parameters) often suffer attention degradation or JSON truncation when forced to produce a single massive nested JSON document containing requirements, risks, milestone schedules, and financial totals.

Instead, ScopeLock uses a sequential 5-step pipeline:

  • Step A (chat gemma4:e4b [requirements]): Extracts requirements and exact substrings from the brief.
  • Step B (chat gemma4:e4b [risks]): Focuses exclusively on technical risks and scope-creep hazards.
  • Step C (chat gemma4:e4b [milestones]): Focuses only on milestone deliverables and integer hours.
  • Tool 1 (execute_tool verify_quotes): Deterministically verifies quotes against the brief text.
  • Tool 2 (execute_tool compute_pricing): Deterministically computes money and contingency in code.
  • Step D (chat gemma4:e4b [client_email]): Drafts the clarification email.

By decomposing the task into atomic stages with Pydantic v2 constrained decoding, Gemma 4 achieved a 100% first-try schema validity rate across our benchmark suite with 0 repair retries.

2. Never Let Language Models Do Arithmetic

A core engineering rule of ScopeLock is: The model is never asked for prices, totals, or percentages.

Instead, the model assigns categorical complexity_tags (e.g. PAYMENTS, COMPLIANCE, AUTH, REALTIME) to requirements. Then, deterministic Python and TypeScript engines compute milestone pricing using a MAX tag rule:

  • A milestone linking requirements with AUTH (1.25x) and PAYMENTS (1.40x) receives an adjusted multiplier of 1.40x (not the inflated product of 1.75x).
  • Adjusted hours = hours * multiplier.
  • Contingency (default 20%) is calculated strictly on adjusted hours.
  • Low price uses unadjusted base hours with 0% contingency; recommended fixed price includes the full buffer.

3. Solving the Ollama num_ctx Truncation Trap

A major trap with local LLM runtimes is context truncation: Ollama's default context window is 4,096 tokens, regardless of what the underlying model architecture supports! When feeding a 10-page RFP, Ollama silently discards the second half of the document without throwing an error.

ScopeLock solves this by:

  1. Setting SCOPELOCK_NUM_CTX explicitly to 16,384 tokens on every chat request.
  2. Estimating tokens in the parser (chars / 4). If a brief exceeds 60% of num_ctx, ScopeLock partitions the document along Markdown headers or page breaks, runs Step A per chunk, and merges requirements in code with automatic ID re-indexing (R1, R2, ...).

4. Sentry Agent Tracing (Metadata Only)

Observability is implemented using Sentry's OpenTelemetry-aligned GenAI manual instrumentation (OTel GenAI v1.28):

  • Root Agent Span: invoke_agent ScopeLock Scoper (op gen_ai.invoke_agent)
  • Chat Spans: chat gemma4:e4b (op gen_ai.chat, tracking gen_ai.usage.input_tokens, output_tokens, scopelock.load_ms, and scopelock.attempt)
  • Tool Spans: execute_tool verify_quotes and execute_tool compute_pricing (op gen_ai.execute_tool)

To preserve our zero-content privacy guarantee:

  • send_default_pii = False
  • include_local_variables = False
  • max_request_body_size = "never"
  • Defensive scrubbing hooks strip any gen_ai.input.messages or gen_ai.output.messages.
  • Telemetry is completely disabled when SENTRY_DSN is empty.

5. The Egress Canary Proof

To prove that no brief content ever leaves the machine, ScopeLock includes an automated egress canary test (test_no_content_egress.py). It injects unique tokens (CANARY-SECRET-<uuid>) into a confidential brief, routes transactions through an in-memory capturing transport, and verifies that neither the canary nor any 8-word sequence appears in telemetry payloads.

Why Does Open Innovation Matter?

  1. Trade Secrets and NDA Survival: In commercial freelancing, cloud LLMs are often legally unusable for client work. Open-weights models running locally allow freelancers to leverage modern AI without risking lawsuits or client confidentiality breaches.
  2. Deterministic Economics ($0 Marginal Cost): As measured in evals/results.md, running our 5 evaluation briefs generated 14,466 tokens. On local Gemma 4, the marginal token cost was $0.00. On proprietary closed APIs (GPT-4o or Claude 3.5 Sonnet), this would cost $0.08 to $0.11 per proposal run. For an active agency analyzing 50 RFPs a month, open weights eliminate subscription overhead.
  3. Hardware Accessibility Ladder: With open models, you are not locked into one giant cloud cluster. Developers on low-end laptops can use gemma4:e2b (~1.6GB VRAM), developers on standard laptops can use gemma4:e4b, and workstations can scale to gemma4:12b—all with a single environment variable change (SCOPELOCK_MODEL).

My Agent Session

This project was built with Google Antigravity paired with Gemini 3.8 Flash. The agent assisted in scaffolding Pydantic schemas, writing the deterministic pricing engine with shared golden test cases, configuring Sentry OpenTelemetry spans, and verifying the egress canary test suite.

My First User

I shared ScopeLock with Karan, an independent full-stack developer who frequently bids on Upwork and direct client RFQs.

We tested ScopeLock on an unstructured client message for a custom marketplace:

  • Time Saved: Karan noted that reading and mapping out the milestones manually usually took him 1.5 to 2 hours. ScopeLock produced a grounded proposal in 3.85 seconds.
  • Scope Creep Saved: ScopeLock flagged the phrase "completely bug-free and scale infinitely" and generated an SLA clause limiting concurrency to 5,000 users. Karan remarked: "I would have probably accepted that verbally without realizing how dangerous 'infinite scaling' is in a fixed-price contract."
  • Willingness to Pay: Karan indicated he would happily pay a one-time fee of $29–$49 for a downloadable desktop pack that integrates custom SOW clause libraries and export templates.

Prize Categories

  1. Best Use of Gemma ($200): Gemma 4 running locally via Ollama powers the multi-stage scoping agent. Evaluated across model ladder (e2b, e4b, 12b) with 100% quote grounding ratio and zero API costs.
  2. Best Use of Render ($200): The ScopeLock workbench is deployed on Render as a static site blueprint (render.yaml) with SPA rewrites and authentic recorded run demo mode.
  3. Best Use of Sentry Agent Tracing ($100): Complete OpenTelemetry GenAI span hierarchy (gen_ai.invoke_agent, gen_ai.chat, gen_ai.execute_tool) with strict metadata scrubbing hooks and a local in-memory TraceRecorder.

Challenge Tags & Discovery

devchallenge #hf26challenge #hacktoberfest #ai #opensource #gemma #ollama #sidehustle

Top comments (0)