README.md

metadata

title: CoastWise
emoji: 🌊
colorFrom: blue
colorTo: green
sdk: gradio
sdk_version: 6.18.0
app_file: app.py
pinned: false
license: mit
short_description: Offline-first, source-backed CA ocean fishing Q&A
tags:
  - build-small-hackathon
  - track:backyard
  - sponsor:openbmb
  - achievement:offbrand
  - achievement:offgrid
  - achievement:tinytitan
  - achievement:bestdemo

CoastWise

CoastWise is an offline-first California ocean regulation and harvest-safety Q&A MVP. It lets users ask practical questions such as "what's the min size of lingcod?" or "can I eat mussels from Pacifica today?" and answers from cached official CDFW/CDPH source snapshots with source links, retrieval time, freshness status, uncertainty, and a next safe action.

The MVP is a decision-support field guide. It does not certify species identification, legality, harvest authorization, or food safety.

Hackathon Positioning

Track: Backyard AI (track:backyard).

Badges and sponsor prizes claimed, each with its honest basis:

• Best MiniCPM Build — sponsor:openbmb: MiniCPM5-1B runs in-process to normalize messy questions ("can I eat mussels from Pacifica today?") into validated, source-backed lookups. The model only interprets — it can never create or override a regulation fact, advisory, source link, date, freshness, status, or next safe action.
• Tiny Titan — achievement:tinytitan: the entire model inventory is one 1.0B model, well under the 4B cap.
• Off Grid — achievement:offgrid: the deterministic core answers every supported question from a bundled official-source cache with no network and no model; the MiniCPM interpreter runs fully in-process from a local GGUF with no external API. CoastWise never depends on a hosted LLM.
• Off Brand — achievement:offbrand: a fully custom "Ocean & Trust" Gradio theme and interface — branded header, status-badge answer cards, an evidence disclosure, example chips, and a freshness bar — well past stock Gradio.
• Best Demo — achievement:bestdemo: a polished, finished app plus a demo video and a social post (links under Demo And Public Evidence).

Deliberately not claimed, to keep every tag honest: Best Agent (CoastWise is a source-validated Q&A pipeline, not a multi-step agent), Best Use of Codex (no Codex-attributed commits in the history), Well Tuned (no fine-tuning), Llama Champion (the model is MiniCPM, not Llama), and the NVIDIA / Modal sponsor prizes (not used).

MVP Scope

• Natural-language Q&A for California ocean sport fishing regulations and CDPH advisory/quarantine topics.
• Statewide official source registry covering CDFW ocean regulations, in-season changes, Northern, Mendocino, San Francisco, Central, Southern, SF Bay, Groundfish Summary, Crabs, CDPH Shellfish Advisories, and CDPH Annual Mussel Quarantine sources.
• Structured answers for the reviewed validation set, including lingcod size, lingcod bag limit, Dungeness crab guidance, CDPH shellfish advisories, and annual mussel quarantine.
• Cited official snippet fallback when cached text exists but structured extraction is incomplete.
• Startup/manual refresh with last-good cache preservation and visible updated/unchanged/failed source status.
• 24-hour stale-data handling that still answers from cache when offline while making verification prominent.
• Session-only handling for questions, optional location text, generated wording, and refresh UI state.
• Photo candidate support is not part of the core source-backed MVP flow.

Model Inventory

Model	Provider	Source URL	Role	Parameters	Runtime mode	Required for core safety	Award relevance
MiniCPM5-1B	OpenBMB	https://huggingface.co/openbmb/MiniCPM5-1B	In-process question interpreter: normalizes messy questions into validated, source-backed candidates; cannot create or override facts	1.0B	In-process GGUF via llama-cpp-python — live on the Space (COASTWISE_LOCAL_MODEL=1), warmed at startup; deterministic fallback if unavailable	No	sponsor:openbmb, achievement:tinytitan, achievement:offgrid

No model fine-tuning is required for the MVP. Model output, when enabled, may only help with interpretation or wording and cannot create or override regulation facts, advisory facts, source links, dates, freshness, status, or next safe action.

All listed models are under the hackathon 32B cap. Tiny Titan remains eligible only while every submitted model stays at or below 4B total parameters.

Enabling The MiniCPM Interpreter

On the live Space the interpreter runs in-process (COASTWISE_LOCAL_MODEL=1), warmed in a background thread at startup so the first question stays fast. It is still optional — the deterministic core answers supported questions with no model and no network. Resolution order is local first, then hosted, otherwise deterministic:

Local, off the grid (no API key): runs MiniCPM5-1B in-process from a GGUF via llama-cpp-python, with no external API. Set COASTWISE_LOCAL_MODEL=1 (the llama-cpp-python dependency must be installed). Optional overrides: COASTWISE_LOCAL_REPO (default openbmb/MiniCPM5-1B-GGUF) and COASTWISE_LOCAL_FILE (default *Q4_K_M.gguf).

Hosted (OpenBMB API): set COASTWISE_LLM_API_KEY to an OpenBMB hosted key. Optional: COASTWISE_LLM_BASE_URL (default https://api.modelbest.cn/v1) and COASTWISE_LLM_MODEL (default MiniCPM5-1B).

When neither is configured, CoastWise stays fully deterministic and still answers supported questions from cache. The model only normalizes the user's question into validated source-backed candidates; it never creates or overrides regulation facts, advisory facts, source links, dates, freshness, status, or the next safe action.

Official Sources And Freshness

Cached official source metadata is bundled for offline lookup. CoastWise treats cached official source snapshots older than 24 hours as stale, but stale cache may still be used when offline with a visible verification warning.

Seed cache retrieval time for the current reviewed source set: 2026-06-15T12:00:00+00:00.

Source	Use	Cached URL
CDFW Ocean Sport Fishing	Statewide ocean sport fishing source registry entry	https://wildlife.ca.gov/Fishing/Ocean/Regulations
CDFW Ocean Sport Fishing In-Season Regulation Changes	Statewide in-season changes source registry entry	https://wildlife.ca.gov/Fishing/Ocean/Regulations/Inseason
CDFW Northern Ocean Region	Northern California ocean region source registry entry	https://wildlife.ca.gov/Fishing/Ocean/Regulations/Fishing-Map/Northern
CDFW Mendocino Ocean Region	Mendocino ocean region source registry entry	https://wildlife.ca.gov/Fishing/Ocean/Regulations/Fishing-Map/Mendocino
CDFW San Francisco Ocean Region	San Francisco ocean region source registry entry	https://wildlife.ca.gov/Fishing/Ocean/Regulations/Fishing-Map/San-Francisco
CDFW Central Ocean Region	Central California ocean region source registry entry	https://wildlife.ca.gov/Fishing/Ocean/Regulations/Fishing-Map/Central
CDFW Southern Ocean Region	Southern California ocean region source registry entry	https://wildlife.ca.gov/Fishing/Ocean/Regulations/Fishing-Map/Southern
CDFW San Francisco Bay Region	San Francisco Bay region source registry entry	https://wildlife.ca.gov/Fishing/Ocean/Regulations/Fishing-Map/SF-Bay
CDFW Groundfish Summary	Lingcod validation-set size and bag facts	https://wildlife.ca.gov/Fishing/Ocean/Regulations/Groundfish-Summary
CDFW Crabs	Dungeness crab validation-set guidance and crab source snippets	https://wildlife.ca.gov/Conservation/Marine/Invertebrates/Crabs
CDPH Shellfish Advisories	Shellfish advisory overlay source	https://www.cdph.ca.gov/Programs/OPA/Pages/Shellfish-Advisories.aspx
CDPH Annual Mussel Quarantine	Annual mussel quarantine overlay source	https://www.cdph.ca.gov/Programs/CEH/DRSEM/Pages/EMB/Shellfish/Annual-Mussel-Quarantine.aspx

Only public official source snapshots and refresh metadata are written to the runtime cache. Questions and optional beach/coastal-area text are not saved by CoastWise.

Demo And Public Evidence

• Demo video: pending, add a public link before final submission.
• Social post: pending, add a public link before final submission.
• Public Space URL: https://huggingface.co/spaces/build-small-hackathon/coastwise

Release Checklist

• README frontmatter includes Build Small hackathon tags.
• Public Hugging Face Space URL is available and listed above.
• Demo video and social post links are listed above.
• Source freshness policy, seed/offline behavior, safety limits, privacy limits, and model inventory are documented in this README.
• Full pytest suite passes before final Space push.

Local Run

python -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python app.py

Test Run

PYTHONPYCACHEPREFIX=/private/tmp/coastwise-pycache .venv/bin/python -m pytest -v

Public Repo Hygiene

Do not commit private user photos, private beach notes, unpublished source material, model weights, .env files, local caches, or private datasets.