Ask SERC

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.

Architecture

• Frontend — React 19 + MUI v7 on Firebase Hosting
• Backend — Google Agent Development Kit (ADK) on Cloud Run (us-east4)
• RAG — Vertex AI Search (VertexAiSearchTool) grounded in SERC's knowledge base
• Web search — Google Search tool for general species info and natural history
• Generation — Gemini 3 Flash Preview via Vertex AI
• Database — Firestore (knowledge gaps, feedback)
• Sync — Cloud Function syncs Google Drive files to GCS; Discovery Engine parses PDFs/DOCX natively

How It Works

1. Volunteers add educational documents (PDFs, DOCX, Google Docs) to a shared Google Drive folder
2. A Cloud Function syncs Drive files daily to GCS and registers them in Discovery Engine (which parses PDFs, DOCX, etc. natively)
3. When a user asks a question, the ADK agent decides which tool to use:
   • SERC Knowledge Base for medical, rehab, husbandry, diet, Virginia wildlife rehab standards
   • Google Search for general species info, natural history, range maps, identification
4. Gemini generates an answer using the Susie persona
5. Every exchange is logged as a knowledge gap for volunteer review at /admin
6. Users can give thumbs up/down feedback on responses

Project Structure

ask-serc/
├── backend/
│   ├── main.py                    # ADK api_server + custom gap/feedback endpoints
│   ├── agents/
│   │   └── susie_agent/
│   │       ├── agent.py           # Agent definition (VertexAiSearchTool + google_search)
│   │       └── prompt.py          # Susie persona + tool routing instructions
│   ├── requirements.txt
│   └── Dockerfile
├── frontend/
│   └── src/
│       ├── App.jsx                # Layout, ADK session creation
│       ├── components/            # ChatWindow, MessageBubble, FeedbackButtons, etc.
│       └── services/api.js        # ADK /run + custom gap tracking endpoints
├── functions/
│   └── main.py                    # Cloud Function: Drive → GCS → Discovery Engine (native parsing)
├── cloudbuild.yaml                # CI/CD: Cloud Build → Cloud Run + Firebase Hosting
└── firebase.json

Development

Backend

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

Frontend

cd frontend
npm install
npm start

Environment Variables

Backend (.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-flash-preview)
FRONTEND_ORIGIN	Allowed CORS origins (comma-separated)

Deployment

Push-triggered via Cloud Build (cloudbuild.yaml): builds Docker image, deploys to Cloud Run, builds React app, deploys to Firebase Hosting.