Okia AI Service

Okia is the AI-powered interview service for YeboJobs. It conducts conversational interviews with job candidates, scores their responses, and generates comprehensive reports for employers.

Overview

• Tech Stack: Python 3.11, FastAPI, SQLAlchemy, Socket.IO
• AI Provider: Claude (Anthropic) via API
• Database: PostgreSQL (shared with YeboJobs)
• Deployment: Google Cloud Run

Key Features

• Real-time conversational interviews via WebSocket
• Dynamic question generation based on job context
• Per-answer scoring with detailed feedback
• Comprehensive interview reports
• SMS notifications for invitations and results
• Webhook integration with YeboJobs backend

Architecture

┌─────────────────────────────────────────────────────────┐
│                    YeboJobs Frontend                     │
│              (React - Okia Interview UI)                 │
└─────────────────────┬───────────────────────────────────┘
                      │ WebSocket / HTTP
                      ▼
┌─────────────────────────────────────────────────────────┐
│                    Okia Service                          │
│  ┌──────────────────────────────────────────────────┐  │
│  │               FastAPI Application                 │  │
│  │  ┌─────────────┐  ┌──────────────┐  ┌─────────┐ │  │
│  │  │ REST API    │  │ Socket.IO    │  │ Webhooks│ │  │
│  │  │ /api/v1     │  │ handlers     │  │         │ │  │
│  │  └──────┬──────┘  └──────┬───────┘  └────┬────┘ │  │
│  │         └────────────────┴───────────────┘      │  │
│  │                          │                       │  │
│  │  ┌──────────────────────────────────────────┐   │  │
│  │  │              Services Layer               │   │  │
│  │  │  ┌───────────┐  ┌───────────┐  ┌──────┐  │   │  │
│  │  │  │ Interview │  │  Claude   │  │Scoring│  │   │  │
│  │  │  │  Service  │  │  Service  │  │Service│  │   │  │
│  │  │  └───────────┘  └───────────┘  └──────┘  │   │  │
│  │  └──────────────────────────────────────────┘   │  │
│  └──────────────────────────────────────────────────┘  │
└─────────────────────┬───────────────────────────────────┘
                      │
        ┌─────────────┼─────────────┐
        ▼             ▼             ▼
   PostgreSQL     Claude API   YeboJobs API
   (Sessions,     (Anthropic)  (Webhooks)
    Messages,
    Scores)

Project Structure

okia-service/
├── app/
│   ├── main.py              # FastAPI entry point
│   ├── config.py            # Configuration & logging
│   ├── api/
│   │   └── v1/
│   │       ├── router.py    # Route aggregator
│   │       ├── endpoints/
│   │       │   ├── sessions.py   # Session CRUD
│   │       │   ├── messages.py   # Interview messages
│   │       │   ├── reports.py    # Report generation
│   │       │   ├── health.py     # Health checks
│   │       │   └── onboarding.py # Service worker onboarding
│   │       └── schemas.py   # Pydantic models
│   ├── services/
│   │   ├── interview.py     # Interview orchestration
│   │   ├── claude.py        # Claude AI integration
│   │   ├── scoring.py       # Answer scoring logic
│   │   ├── sms.py           # SMS notifications
│   │   └── user_stats.py    # YeboScore updates
│   ├── sockets/
│   │   ├── manager.py       # Socket.IO setup
│   │   └── handlers.py      # Real-time event handlers
│   └── db/
│       ├── session.py       # Database connection
│       ├── base.py          # SQLAlchemy base
│       └── models.py        # ORM models
├── requirements.txt
├── Dockerfile
└── cloudbuild.yaml

Environment Variables

# Database
DATABASE_URL=postgresql+asyncpg://...

# Claude AI
ANTHROPIC_API_KEY=sk-ant-...
CLAUDE_MODEL=claude-sonnet-4-20250514

# Security
OKIA_API_KEY=your-api-key          # For YeboJobs → Okia auth
OKIA_WEBHOOK_SECRET=webhook-secret  # For Okia → YeboJobs auth

# SMS (Twilio)
TWILIO_ACCOUNT_SID=...
TWILIO_AUTH_TOKEN=...
TWILIO_PHONE_NUMBER=+1...

# Server
PORT=8080
DEBUG=false
CORS_ORIGINS=https://yebojobs.pages.dev,https://yebojobs.com

Interview Flow

1. Session Creation (via YeboJobs backend)

   • YeboJobs creates session with candidate/job details
   • Okia returns session token and interview URL

2. Interview Start (candidate opens URL)

   • Candidate connects via WebSocket
   • Okia sends personalized greeting
   • Timer starts

3. Question Loop

   • Okia generates contextual question
   • Candidate answers via chat
   • Okia scores answer in real-time
   • Okia generates follow-up or next question
   • Repeat until max questions or time limit

4. Completion

   • Okia generates closing message
   • Comprehensive report is created
   • Webhook notifies YeboJobs with scores
   • SMS sent to candidate with result

Quick Links

• API Endpoints
• Services
• Database Models