ScopePilot

Turn Client Briefs Into Professional Proposals

A 100% Local-First, Privacy-Preserving Project Scope & Proposal Generator for Freelancers, Independent Software Engineers, and Digital Studios.

🌐 Live Cloud Demo • 💻 Local Installation • 📖 Documentation • 🛡️ Privacy Architecture

Freelance developers, UI/UX designers, and small agencies lose countless unbillable hours deciphering vague, unstructured client messages (emails, Slack chats, informal briefs) and converting them into professional proposals.

Traditional approaches force an uncomfortable compromise:

1. Manual Scoping: Spending 3–6 hours drafting deliverables, timelines, assumptions, and pricing tables from scratch.
2. Cloud AI SaaS Tools: Pasting confidential client ideas, budgets, and proprietary requirements into commercial third-party cloud LLMs, exposing private intellectual property and accumulating monthly subscription fees.

ScopePilot solves this by running an open-weight, locally hosted Gemma 3 model via Ollama. It parses incoming client briefs on your own computer, structures actionable deliverables, flags missing information, plans milestones, and generates client-ready PDF and Markdown proposals in seconds — without your client data leaving your machine.

• 🛡️ 100% Local-First & Confidential: Zero cloud LLM APIs. No OpenAI, Anthropic, or external endpoints. All inference runs over local loopback (http://127.0.0.1:11434).
• 🧭 Top Horizontal Navigation Bar: Modern SaaS header featuring balanced ScopePilot branding, clean section navigation, and a compact real-time AI Engine status pill.
• ⚡ Zero-Latency UI & Performance Caching: In-memory TTL caching for Ollama health checks, mtime-based proposal index caching, and on-demand export compilation to ensure instant tab switching.
• 🔍 Multi-Stage Brief Analysis: Deconstructs vague client messages into confirmed facts, functional requirements, and critical missing details (e.g., missing budgets or deadlines).
• 📐 Structured Deliverables & Exclusions: Automatically defines what is in scope and explicitly documents what is excluded to prevent project scope creep.
• 💰 Deterministic Commercial Engine: Generates transparent, itemized work estimates based on industry benchmarks. Math is verified in Python — never left to hallucinated LLM arithmetic.
• 🏷️ Ethical AI Labeling: Explicitly prefixes unconfirmed points with AI-generated assumption — requires client confirmation and Recommended — subject to freelancer approval.
• 📄 Client-Grade PDF & Markdown Exports: Formatted multi-page PDF generation via ReportLab with headers, footers, page numbering, tables, and currency support (USD, INR, EUR, GBP).
• ✏️ Interactive Proposal Editor & Section Regeneration: In-place editing of any section with the ability to ask Gemma 3 to rewrite specific sections without modifying the rest of the document.
• 💻 Device-Local Persistence: Proposals are stored as plain JSON files in your local project workspace, protected by your operating system permissions.
• 🌐 Dual-Mode Deployment Architecture: Switch seamlessly between full local edition and read-only, safe cloud_demo mode via environment variable or Streamlit secrets.

ScopePilot features first-class dual-mode support via core/app_mode.py:

Mode resolution priority:

1. Environment variable: SCOPEPILOT_MODE=cloud_demo
2. Streamlit secret: SCOPEPILOT_MODE = "cloud_demo" in .streamlit/secrets.toml
3. Fallback default: local

Most AI productivity tools are thin wrappers around paid cloud APIs. ScopePilot is deliberately built on open-weight AI:

1. True Client Confidentiality: When clients share trade secrets, proprietary workflows, or early-stage product concepts, sending that data to remote AI servers can breach NDAs. Open weights protect both you and your client.
2. Zero Inference Costs: You never pay per-token fees, monthly API subscriptions, or rate-limit penalties.
3. Independence from Provider Terms: Your business workflow is insulated from hosted model deprecations, censorship policy shifts, or API price hikes.
4. Offline Capability: Once the weights are downloaded, ScopePilot functions seamlessly on flights, remote locations, or air-gapped environments.

ScopePilot/
├── app.py                      # Main Streamlit application entrypoint & mode branching
├── config.py                   # App configuration and environment defaults
├── requirements.txt            # Production runtime dependencies (pinned)
├── requirements-dev.txt        # Development & test dependencies (pytest, pytest-mock)
├── .streamlit/
│   ├── config.toml             # Streamlit cloud theme and server configuration
│   └── secrets.toml.example    # Example secrets configuration for cloud_demo mode
├── core/                       # AI pipeline, Pydantic schemas, and validation
│   ├── app_mode.py             # Centralized mode detection (local vs cloud_demo)
│   ├── ai_engine.py            # AI facade
│   ├── schemas.py              # Pydantic v2 data models
│   ├── prompts.py              # Constrained system & stage prompts
│   ├── validators.py           # Logic, timeline, and pricing validators
│   └── proposal_generator.py   # Multi-stage proposal generation pipeline
├── services/                   # Service layer
│   ├── ollama_service.py       # Local Ollama REST client with TTL caching & JSON parsing
│   ├── cloud_demo_service.py   # Safe read-only demo storage & stubbed Ollama service
│   ├── analysis_service.py     # Brief deconstruction service
│   ├── pricing_service.py      # Deterministic pricing engine
│   ├── export_service.py       # ReportLab PDF & Markdown generator
│   └── storage_service.py      # Atomic local JSON storage with mtime caching
├── components/                 # Streamlit UI views
│   ├── navbar.py               # Top horizontal navbar & mode-aware status pill
│   ├── dashboard.py            # Customer-facing stats, sample explorer & install CTA
│   ├── proposal_form.py        # Proposal input, sample loader & demo guard
│   ├── proposal_view.py        # Proposal viewer, editor & cached exports
│   ├── settings_view.py        # Configuration, consultant profile & privacy controls
│   └── about_view.py           # Product philosophy & deployment options
├── assets/                     # Stylesheet & wide branding assets
├── data/proposals/             # Private local proposal storage (.gitignore)
├── examples/                   # Sample project briefs & bundled demo proposal
│   ├── demo_proposal.json      # Pre-generated comprehensive sample for cloud_demo
│   ├── ecommerce.json          # Sustainable apparel store sample brief
│   ├── portfolio.json          # Creative portfolio sample brief
│   └── mobile_app.json         # Clinic booking mobile app sample brief
└── tests/                      # Automated pytest suite (51 unit & integration tests)
    ├── test_cloud_mode.py      # Dual-mode safety, read-only storage & mock tests
    ├── test_schemas.py         # Pydantic schema validation tests
    ├── test_pricing.py         # Deterministic pricing engine tests
    ├── test_exports.py         # PDF and Markdown export rendering tests
    ├── test_storage.py         # Storage persistence and cache invalidation tests
    ├── test_validators.py      # Proposal integrity & sanity check tests
    ├── test_ollama_service.py  # Ollama REST interaction & JSON extraction tests
    └── test_integration_live.py # Live Ollama inference pipeline test

• Python: Python 3.12 or 3.13 installed.
• Ollama: Installed from ollama.com.

Open PowerShell and start Ollama (if not already running as a Windows service):

ollama run gemma3:1b

Verify Ollama is responding:

curl http://localhost:11434/api/tags

git clone https://github.com/sayuj5/ScopePilot.git
cd ScopePilot
python -m venv venv
.\venv\Scripts\python.exe -m pip install --upgrade pip
.\venv\Scripts\python.exe -m pip install -r requirements.txt

Copy .env.example to .env (optional, safe defaults are pre-configured):

cp .env.example .env

.\venv\Scripts\python.exe -m streamlit run app.py

Open your browser at http://localhost:8501.

ScopePilot is pre-configured for zero-cost deployment on Streamlit Community Cloud:

1. Fork or push this repository to GitHub.
2. Visit share.streamlit.io and click "New app".
3. Select your repository, branch (main), and set the Main file path to app.py.
4. In Advanced settings → Secrets, add:

   SCOPEPILOT_MODE = "cloud_demo"

5. Click Deploy.

ScopePilot will automatically boot in cloud_demo mode:

• Live model inference is disabled.
• Bundled pre-generated demo proposals are loaded.
• All disk modifications are blocked.
• PDF and Markdown exports remain fully operational.

ScopePilot includes a comprehensive test suite (51 tests) covering schemas, validation, pricing arithmetic, storage operations, export rendering, cloud mode safety, and Ollama interactions:

.\venv\Scripts\python.exe -m pip install -r requirements-dev.txt
.\venv\Scripts\python.exe -m pytest -v

To run cloud demo mode tests specifically:

.\venv\Scripts\python.exe -m pytest tests/test_cloud_mode.py -v

ScopePilot ships with pre-built sample briefs to test the local AI pipeline instantly:

1. Sustainable E-commerce Store (examples/ecommerce.json): Tests clothing catalog, variants, Stripe payment gateway, and order fulfillment.
2. Designer Portfolio (examples/portfolio.json): Tests creative studio showcase with micro-animations and Google PageSpeed requirements.
3. Clinic Appointment Booking (examples/mobile_app.json): Tests multi-location calendar booking, Twilio SMS alerts, and healthcare privacy constraints.

In local mode, click "⚡ Load Sample Client Brief" on the New Proposal screen to populate any sample instantly.

• All proposals in local mode are saved to data/proposals/ and are ignored in Git by default (.gitignore).
• In cloud demo mode, no user input or proposal data is ever written to disk or transmitted off-server.
• No telemetry, analytics, or outbound web tracking calls exist in the codebase.
• See docs/PRIVACY.md for full data protection guidelines.

• Public Cloud Demo Limitation: The public demonstration runs on Streamlit Community Cloud without access to local GPU hardware. Live model inference is disabled in the web demo; explore pre-generated samples or install ScopePilot locally for full inference.
• Model Nuance: Gemma 3 1B is optimized for speed and laptop execution. For complex enterprise architectures, human review and manual adjustment of itemized hours in the Proposal Editor is strongly recommended.
• First Download Internet Requirement: While ScopePilot runs offline after installation, pulling the initial Ollama runtime and Gemma model weights requires an internet connection.

Submission for DEV Open-Source AI Challenge Week 2: Side Hustle:

• #devchallenge
• #hf26challenge

This project is licensed under the MIT License.