--- 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 ```bash python -m venv .venv .venv/bin/python -m pip install -r requirements.txt .venv/bin/python app.py ``` ## Test Run ```bash 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.