Sarah Brain API 🤖

A lean, production-ready AI Secretary API powered by LangGraph + Groq, backed by Supabase, and designed to be orchestrated by n8n for WhatsApp automation.

---

Architecture

WhatsApp User
     ↓
[n8n: WhatsApp Trigger]
     ↓
[n8n: HTTP Request → Sarah Brain API (Render)]
     ↓
[LangGraph Agent + Tools → Supabase DB]
     ↓
[n8n: WhatsApp Send Message]
     ↓
WhatsApp User

---

Folder Structure

sarah-brain-api/
├── main.py           # FastAPI entrypoint (single /api/v1/brain endpoint)
├── ai_brain.py       # Sarah's LangGraph brain — DO NOT MODIFY
├── database.py       # Supabase PostgreSQL data layer
├── requirements.txt  # Python dependencies
├── render.yaml       # One-click Render deploy config
├── .env.example      # Environment variable template
└── .gitignore

---

Step 1: Set Up Supabase (Free Database)

1. Go to https://supabase.com and sign up (free, no credit card).
2. Click "New Project" → give it a name (e.g. sarah-clinic) → set a strong database password → click Create.
3. Wait ~2 minutes for the project to spin up.
4. Go to Project Settings → Database (left sidebar).
5. Scroll to "Connection string" → select the URI tab.
6. Copy the full URI. It looks like:

   postgresql://postgres:[YOUR-PASSWORD]@db.xxxxxxxxxxxx.supabase.co:5432/postgres
   

7. Replace [YOUR-PASSWORD] with the password you set. This is your DATABASE_URL.

✅ Tables are created automatically on first startup. No manual SQL needed.

---

Step 2: Local Test (Optional but Recommended)

# 1. Create virtual environment
python -m venv venv
venv\Scripts\activate        # Windows
# source venv/bin/activate   # Mac/Linux

# 2. Install dependencies
pip install -r requirements.txt

# 3. Create your .env file
cp .env.example .env
# Fill in GROQ_API_KEY, DATABASE_URL, and ADMIN_SECRET

# 4. Run locally
uvicorn main:app --port 8000 --reload

Test it:

curl -X POST http://localhost:8000/api/v1/brain \
  -H "Content-Type: application/json" \
  -H "X-Admin-Token: your_secret_here" \
  -d '{"phone_number": "923001234567", "message": "Hi, I want to book an appointment", "contact_name": "Ahmed Khan"}'

Expected response:

{
  "status": "success",
  "phone_number": "923001234567",
  "reply": "Hi Ahmed! Of course, let me check what we have available..."
}

---

Step 3: Deploy to Render (Free Hosting)

1. Create a new GitHub repository named sarah-brain-api.
2. Push this folder to it:

   git init
   git add .
   git commit -m "Initial deploy"
   git remote add origin https://github.com/YOUR_USERNAME/sarah-brain-api.git
   git push -u origin main

3. Go to https://render.com → New → Web Service.
4. Connect your GitHub account and select the sarah-brain-api repository.
5. Render will auto-detect render.yaml. Click Apply.
6. Go to Environment tab and add these variables:

   Key	Value
   GROQ_API_KEY	Your Groq API key
   DATABASE_URL	Full Supabase URI
   ADMIN_SECRET	A strong secret (e.g. clinic_secret_2026)

7. Click Deploy. Wait ~3 minutes.
8. Your live URL will be: https://sarah-brain-api.onrender.com

⚠️ Free Render services "sleep" after 15 minutes of inactivity. n8n's first message after a long gap may take 30–60 seconds. To avoid this, use Render's free "Uptime Robot" integration or upgrade to the $7/month Starter plan.

---

Step 4: Configure n8n Workflow

Node 1: WhatsApp Trigger

• Event: Message Received
• No changes needed — this receives the inbound message.

Node 2: HTTP Request (Sarah's Brain)

• Method: POST
• URL: https://sarah-brain-api.onrender.com/api/v1/brain
• Headers:

  X-Admin-Token: your_secret_here
  Content-Type: application/json
  

• Body (JSON):

  {
    "phone_number": "{{ $('WhatsApp Trigger').item.json.messages[0].from }}",
    "message": "{{ $('WhatsApp Trigger').item.json.messages[0].text.body }}",
    "contact_name": "{{ $('WhatsApp Trigger').item.json.contacts[0].profile.name }}"
  }

Node 3: Wait

• Wait: 3 Seconds
• Makes Sarah feel human (not instant-bot behaviour).

Node 4: WhatsApp Send Message

• Recipient: {{ $('WhatsApp Trigger').item.json.messages[0].from }}
• Text Body: {{ $('HTTP Request').item.json.reply }}

---

Cost Summary

Service	Plan	Cost
Render	Free (or $7/mo Starter for no sleep)	$0–$7
Supabase	Free (500MB, 50k rows)	$0
Groq	Free (fast Llama 3.3)	$0
n8n Cloud	Free (5 workflows, 2500 exec/mo)	$0
Meta WhatsApp	Free (1000 conversations/mo)	$0

Total: $0/month for a small clinic.

---

Frequently Asked Questions

Q: What if the client gets more than 1,000 conversations/month?
A: Meta charges $0.005–$0.025 per conversation beyond the free tier. For a clinic, this is unlikely.

Q: Can I change Sarah's persona for a different client?
A: Yes. Set the SYSTEM_PROMPT environment variable on Render with the new persona text. No code changes needed.

Q: Is the data safe?
A: All patient data is stored in Supabase (ISO 27001 certified). The API is secured with the ADMIN_SECRET header.