README.md

---
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.