agentdocs/ARCHITECTURE.md

Architecture

Outbush AI is intentionally compact.

flowchart TD
  Browser["Phone browser / HF Space browser"] --> App["app.py Gradio Server + FastAPI routes"]
  App --> Core["outbush_ai/core.py"]
  Core --> RAG["retrieval.py SQLite FTS5"]
  RAG --> DB["data/outbush_knowledge.sqlite"]
  Core --> Content["content.py source corpus, checklist, danger cards"]
  Core --> Llama["optional llama.cpp text model"]
  Core --> Vision["optional MiniCPM-V llama-mtmd-cli"]
  Core --> Species["optional field-tuned species classifier JSON"]
  Core --> Weather["weather.py cached/live weather pack"]

Request Flow

• /api/chat searches the local knowledge pack, applies risk banners, and asks llama.cpp to synthesize the answer. If the text model is unavailable, it says so instead of emitting a deterministic chat answer.
• /api/photo performs local pixel analysis, optional field-tuned species classification, optional MiniCPM-V classification, then applies conservative care notes.
• /api/firstaid searches the local RAG pack for a topic and returns first aid steps plus do-not guidance.
• /api/encyclopedia exposes direct local RAG search.
• /api/encyclopedia/random returns a random local knowledge item for discovery mode.
• /api/weather separates broad climate/profile guidance from cached or live weather pack data; /api/weather-locations serves the location typeahead catalogue.
• /api/health reports whether SQLite, llama.cpp/Nemotron, MiniCPM-V, and the species classifier are active; on Spaces it also exposes text-model setup progress.

Data Flow

outbush_ai/content.py plus outbush_ai/expanded_content.py are the source of truth for RAG items. Run python scripts/build_knowledge_db.py after editing them. Tests expect the packaged SQLite database to be present, FTS-enabled, and in the 325-650 item range.

The dangerous-species image classifier is trained by modal_jobs/outbush_species_finetune.py. It uploads artifacts to Hugging Face and the app can run from the checked-in JSON model at models/outbush_dangerous_species_classifier.json.

Runtime Philosophy

The model paths are additive but Ask mode is model-first. llama.cpp/Nemotron should provide the prose answer, while deterministic code supplies risk banners, safety footers, source selection, photo guardrails, first-aid structures, and weather/location plumbing. Space startup warms both the text runtime and MiniCPM runtime in background threads so health can be checked while large model files are still downloading.