A RAG chatbot for Southeastern Reptile Conservation (SERC). The chatbot is voiced as Susie, one of SERC's ambassador Eastern Box Turtles, and helps volunteers and wildlife rehabilitators find information about husbandry, wound care, enclosure setup, and rehabilitation protocols.
- Frontend — React 19 + MUI v7 on Firebase Hosting
- Backend — Custom FastAPI agentic loop using
google-genaion Cloud Run (us-east4) - RAG — Vertex AI Search (Discovery Engine) grounded in SERC's knowledge base
- Web search — Gemini built-in Google Search grounding for general species info and natural history
- Generation — Gemini 3.8 Flash via Vertex AI
- Sessions — Firestore (conversation history, knowledge gaps, feedback)
- Sync — Cloud Function syncs Google Drive files to GCS; Discovery Engine parses PDFs/DOCX natively
- Volunteers add educational documents (PDFs, DOCX, Google Docs) to a shared Google Drive folder
- A Cloud Function syncs Drive files daily to GCS and registers them in Discovery Engine
- When a user asks a question, Susie's agentic loop decides which tool to use:
- search_serc_knowledge_base — calls Discovery Engine for medical, rehab, husbandry, protocols
- google_search — Gemini built-in grounding for general species info, natural history, identification
- Gemini generates an answer using the Susie persona and returns it with source citations
- Every exchange is logged as a knowledge gap for volunteer review at
/admin - Users can give thumbs up/down feedback on responses
ask-serc/
├── backend/
│ ├── main.py # FastAPI app: agentic loop, session management, gap/feedback endpoints
│ ├── agents/
│ │ └── susie_agent/
│ │ ├── agent.py # Legacy ADK agent definition (not used at runtime)
│ │ └── prompt.py # Susie persona + tool routing instructions
│ ├── requirements.txt
│ └── Dockerfile
├── frontend/
│ └── src/
│ ├── App.jsx # Layout, session creation
│ ├── components/ # ChatWindow, MessageBubble, FeedbackButtons, etc.
│ └── services/api.js # /run + session + gap tracking API calls
├── functions/
│ └── main.py # Cloud Function: Drive → GCS → Discovery Engine (native parsing)
├── cloudbuild.yaml # CI/CD: Cloud Build → Cloud Run + Firebase Hosting
└── firebase.json
cd backend
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env # fill in real values
python main.pycd frontend
npm install
npm startBackend (.env or Secret Manager):
| Variable | Description |
|---|---|
GCP_PROJECT_ID |
GCP project ID |
DATASTORE_ID |
Full Discovery Engine data store resource path |
GOOGLE_SERVICE_ACCOUNT_JSON |
Service account key JSON |
GOOGLE_CLOUD_LOCATION |
Vertex AI location (default: global) |
GEMINI_MODEL |
Gemini model name (default: gemini-3.8-flash) |
FRONTEND_ORIGIN |
Allowed CORS origins (comma-separated) |
Push-triggered via Cloud Build (cloudbuild.yaml): builds Docker image, deploys to Cloud Run, builds React app, deploys to Firebase Hosting.
gcloud builds submit --project=ask-sercThe Cloud Function syncs Google Drive → GCS → Discovery Engine daily. To force a full re-index:
gcloud functions call sync-drive-to-gcs --data='{"force": "true"}' --project=ask-serc