agentdocs/README.md

Outbush AI Agent Guide

Outbush AI is a small offline-first Gradio/FastAPI field assistant for Australian bushwalking. The app is designed to run in three places:

• local development on a laptop
• Hugging Face Spaces for the hackathon demo
• a Raspberry Pi 5 acting as a local Wi-Fi appliance

The user-facing app is deliberately conservative. Ask mode is model-first and should not fabricate prose when the text model is unavailable; first-aid, photo, weather, checklist, and encyclopedia routes still keep structured safety guidance useful offline.

Start Here

• app.py wires the HTTP API and Gradio server.
• outbush_ai/frontend.py contains the whole browser UI as a static HTML string.
• outbush_ai/core.py is the main product logic and safety orchestration.
• outbush_ai/content.py is the offline source corpus for core RAG and checklist/danger cards.
• outbush_ai/expanded_content.py generates the larger park, ranger-tip, wildlife, plant, cloud, bush-tucker, and mushroom RAG pack.
• outbush_ai/retrieval.py loads the packaged SQLite FTS5 knowledge database.
• outbush_ai/vision.py wraps the optional OpenBMB MiniCPM-V 4.6 GGUF runtime through llama.cpp llama-mtmd-cli.
• outbush_ai/species_model.py wraps the lightweight field-tuned dangerous-species classifier.
• scripts/build_knowledge_db.py rebuilds data/outbush_knowledge.sqlite from content.py.

Local Commands

. .venv/bin/activate
python scripts/build_knowledge_db.py
python -m unittest discover -s tests
python app.py

Open http://127.0.0.1:7860.

Non-Negotiables

• Never tell a user a wild mushroom, plant, animal, or marine creature is safe to touch or eat from app output.
• Snake bites are treated as potentially life-threatening and route to Triple Zero (000).
• Funnel-web and mouse spider bites route to emergency pressure immobilisation guidance.
• Redback spider guidance is intentionally different from funnel-web guidance.
• Offline weather/climate guidance must not masquerade as a live forecast.
• The app must still pass tests with no model binaries present.
• The packaged RAG DB should stay in the 325-650 item range unless the tests and docs are deliberately updated.