WorkAbroad AI

Sara — AI Recruitment Specialist for Overseas Employment

$ boot sara
  WorkAbroad AI v2.0-dev — Sara, Overseas Recruitment Specialist
  ✓ Pydantic AI agent        ✓ Supabase + pgvector RAG
  ✓ Orchestrator reliability ✓ Docker & CI/CD
  ✓ ECS deployment (HTTP)    ✓ Supabase anonymous auth
  status: LIVE → waiting for applicants...

---

Mission

Automate the first stage of overseas recruitment while maintaining the professionalism of an experienced human recruiter. Sara conducts interviews, collects applicant information, evaluates eligibility, answers agency questions, and guides applicants through documentation — reducing recruiter workload.

Sara behaves like a recruitment officer, not a generic chatbot.

What Sara Can Do

• Conduct applicant interviews
• Collect applicant profiles
• Determine eligibility
• Explain recruitment requirements
• Answer agency knowledge questions
• Guide applicants through documentation
• Reduce recruiter workload

---

Feature Status

Feature	Status
Pydantic AI Agent	✅ Done
Supabase Data Layer	✅ Done
RAG via pgvector	✅ Done
Orchestrator Reliability	✅ Done
Docker & Deployment	✅ Done
CI/CD Pipeline	✅ Done
Supabase Anonymous Auth	✅ Done
ECS Deployment (HTTP)	✅ Live

---

Technology Stack

Technology	Purpose
Python 3.12	Runtime
FastAPI	Web framework
Pydantic AI	AI agent framework
Groq	Primary LLM provider
Cerebras	Fallback LLM (rate-limit)
Gemini	Secondary LLM provider
Supabase	PostgreSQL + pgvector
Sentence Transformers	Embeddings
Alibaba Cloud ECS	Production server
Docker	Containerization
Ruff · mypy · pytest	Lint · type-check · tests

---

Architecture

Applicant
   │
   ▼
FastAPI (thin routes)
   │
   ▼
Pydantic AI Agent (Sara)
   ├── Tools: business_rules, eligibility, knowledge_search, question_planner
   ├── Dependency injection: Supabase repositories
   └── LLM: Groq | Gemini (via Pydantic AI model abstraction)
   │
   ▼
Supabase
   ├── PostgreSQL: sessions, profiles, conversations, users
   └── pgvector: knowledge embeddings + RAG

Architectural Rules

• Business logic stays deterministic — never in LLM prompts
• One canonical retrieval path — knowledge flows through Supabase pgvector
• LLM only generates natural language — decisions come from tools
• API routes stay thin — no business logic in routes
• Repositories own data access — no raw SQL outside repositories

---

Interview Flow

Country → Age → Gender → Civil Status → Children → Passport
→ Government ID → PSA Birth Certificate → Marriage Certificate
→ Education → Domestic Helper Experience → Previous Abroad
→ Previous Country → Years Experience → Medical → TESDA
→ OWWA → Interview Complete

Dynamic rules are handled by the Decision Engine — deterministic, not prompted.

---

Running Locally

git clone https://github.com/WSlag/workabroadai.git
cd workabroadai
python -m venv venv
source venv/bin/activate        # Windows: venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env            # fill in your API keys
uvicorn api.main:app --reload

---

Deployment

Prerequisites

• Docker & Docker Compose
• A domain name pointed at your server
• Alibaba Cloud ECS (Ubuntu 22.04 recommended)
• Supabase project (URL + keys)

Local Build & Run

cp .env.example .env
docker compose up --build       # http://localhost:8000

Production Deploy

# 1. Configure .env (GROQ_API_KEY, SUPABASE_URL, API_KEY, PYDANTIC_AI_MODEL, ...)
# 2. Set host variables
export REMOTE_HOST=your-ecs-ip
export REMOTE_USER=root
export DOMAIN=yourdomain.com
# 3. Ship it
bash deploy.sh

The script copies deployment files, installs Let's Encrypt for HTTPS, builds and starts containers, then runs a health check. The Dockerfile health check pings POST /chat every 30s; Nginx rate-limits /chat to 10 req/s per IP.

---

Production Environment Variables

Variable	Purpose
GROQ_API_KEY	Primary LLM provider
CEREBRAS_API_KEY	Fallback LLM (rate-limit)
SUPABASE_URL	PostgreSQL + pgvector
SUPABASE_SERVICE_KEY	Database admin access
SUPABASE_ANON_KEY	Client-side anonymous auth (applicant portal)
API_KEY	Dashboard authentication
PYDANTIC_AI_MODEL	Model identifier

---

Roadmap & Docs

• MASTER_ROADMAP.md — product roadmap
• IMPLEMENTATION_PLAN.md — current implementation plan
• .agents/PRDs/workabroad-ai-v2.prd.md — PRD