Skip to content

Quickstart

Get ScamShield AI running in 15 minutes -- from clone to your first scam-detection request.

1. Clone the repository

git clone https://github.com/your-org/scamshield-ai.git
cd scamshield-ai

2. Create a Python virtual environment

ScamShield uses Python 3.11. The venv must live inside functions/ because Firebase CLI expects it there during deployment.

python3.11 -m venv functions/venv
source functions/venv/bin/activate

Python version matters

Firebase Cloud Functions 2nd gen requires Python 3.11. Using a different version may cause deployment failures. Verify with python --version after activating the venv.

3. Install dependencies

pip install -r functions/requirements.txt
pip install pytest ruff  # dev tools

4. Configure environment variables

Copy the example file and fill in your keys:

cp .env.example .env.local

Edit .env.local:

# Required: Get from https://aistudio.google.com/app/apikey
GEMINI_API_KEY=your-gemini-api-key-here

# Required: Generate your own API key for endpoint auth
# GUVI sends this in the x-api-key header when calling your endpoint
SCAMSHIELD_API_KEY=scamshield-your-generated-key-here

Generate a secure API key:

python -c "import secrets; print(f'scamshield-{secrets.token_hex(16)}')"

5. Run the test suite

PYTHONPATH=functions pytest tests/ -v

All tests should pass. If any fail, check that your Python version is 3.11 and all dependencies installed correctly.

Tests never call real APIs

The test suite mocks all external services (Gemini, Firestore, GUVI callback). You do not need valid API keys to run tests.

6. Deploy to Firebase

First, make sure you are logged in and have a Firebase project set up (see Prerequisites and Configuration if you have not done this yet):

firebase login
firebase use your-gcp-project-id

Set your secrets in Firebase Secret Manager:

firebase functions:secrets:set GEMINI_API_KEY
firebase functions:secrets:set SCAMSHIELD_API_KEY

Deploy:

firebase deploy --only functions

First deploy takes 3-5 minutes

Subsequent deploys are faster. The CLI will print the function URL when done.

7. Test with curl

Once deployed, send a test request to verify the endpoint is working:

curl -X POST \
  https://asia-south1-your-gcp-project-id.cloudfunctions.net/guvi_honeypot \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_SCAMSHIELD_API_KEY" \
  -d '{
    "sessionId": "test-session-001",
    "currentMessage": {
      "role": "scammer",
      "content": "Hello, I am calling from SBI bank. Your account has been compromised. Please share your OTP to secure it."
    },
    "conversationHistory": []
  }'

You should get a JSON response with:

  • A persona-appropriate reply engaging the scammer
  • Scam classification (e.g., BANKING_FRAUD)
  • Extracted evidence (phone numbers, UPI IDs, bank accounts, etc.)
{
  "sessionId": "test-session-001",
  "response": "Oh my! SBI bank? Which branch are you calling from, beta?...",
  "scamDetected": true,
  "scamType": "BANKING_FRAUD",
  "confidence": 0.92,
  "persona": "Sharma Uncle",
  "extractedIntelligence": {
    "bankAccounts": [],
    "upiIds": [],
    "phoneNumbers": [],
    "urls": [],
    "emailAddresses": [],
    "names": [],
    "organizations": ["SBI"],
    "cryptoWallets": [],
    "socialMediaHandles": [],
    "otherEvidence": [],
    "keywords": ["OTP", "account compromised"]
  }
}

What's next?