encoach_be_odoo19/ENCOACH_AI_KEYS.md

# EnCoach AI & Service Keys Configuration

All API keys are stored as Odoo **System Parameters** (`ir.config_parameter`).

---

## How to Set Keys

### Via Odoo UI

1. Login as `admin` / `admin` at http://127.0.0.1:8069/web
2. Navigate to **Settings > Technical > Parameters > System Parameters**
3. Search for `encoach.` to filter all EnCoach keys
4. Click a parameter and paste your key into the **Value** field
5. Save — changes take effect immediately (no restart needed)

### Via Terminal

```bash
cd /Users/yamenahmad/projects2026/odoo/odoo19/odoo

../.conda-envs/odoo19/bin/python odoo-bin shell -c ../odoo.conf -d encoach <<'EOF'
params = env['ir.config_parameter'].sudo()
params.set_param('encoach.openai_api_key', 'sk-your-key-here')
params.set_param('encoach.aws_access_key_id', 'AKIA...')
params.set_param('encoach.aws_secret_access_key', 'your-aws-secret')
params.set_param('encoach.elai_token', 'your-elai-token')
params.set_param('encoach.gptzero_api_key', 'your-gptzero-key')
params.set_param('encoach.jwt_secret', 'a-strong-random-secret-256-bits')
env.cr.commit()
print("All keys set.")
EOF
```

---

## Key Reference

### Core

| Parameter | Description | Required | Where to Get |
|-----------|-------------|----------|-------------|
| `encoach.jwt_secret` | JWT signing secret for API authentication | Yes | Generate a random 256-bit string |
| `encoach.jwt_expiry_hours` | JWT token expiry in hours (default: 72) | No | Set any integer |

### OpenAI (GPT-4o, Whisper)

Used by: Exam generation, writing/speaking evaluation, grading, training tips.

| Parameter | Description | Required | Where to Get |
|-----------|-------------|----------|-------------|
| `encoach.openai_api_key` | OpenAI API key | Yes | https://platform.openai.com/api-keys |

**Models used:**
- `gpt-4o` — Exam generation, evaluation, grading, training
- `whisper-1` — Audio transcription (speaking evaluation)

### AWS (Polly TTS)

Used by: Listening exam audio generation, instruction audio.

| Parameter | Description | Required | Where to Get |
|-----------|-------------|----------|-------------|
| `encoach.aws_access_key_id` | AWS IAM Access Key ID | Yes | https://console.aws.amazon.com/iam/ |
| `encoach.aws_secret_access_key` | AWS IAM Secret Access Key | Yes | Same as above |

**AWS services used:**
- **Amazon Polly** — Text-to-speech for listening exam audio
- **Region:** Configured in `polly_service.py` (default: `us-east-1`)

**Required IAM permissions:**
```json
{
  "Effect": "Allow",
  "Action": ["polly:SynthesizeSpeech"],
  "Resource": "*"
}
```

### ELAI.io (Avatar Videos)

Used by: Speaking exam video generation with AI avatars.

| Parameter | Description | Required | Where to Get |
|-----------|-------------|----------|-------------|
| `encoach.elai_token` | ELAI API token | For speaking videos | https://elai.io/api |

### GPTZero (Plagiarism Detection)

Used by: AI-generated content detection in writing submissions.

| Parameter | Description | Required | Where to Get |
|-----------|-------------|----------|-------------|
| `encoach.gptzero_api_key` | GPTZero API key | Optional | https://gptzero.me/api |

### Stripe (Payments)

Used by: Subscription checkout.

| Parameter | Description | Required | Where to Get |
|-----------|-------------|----------|-------------|
| `encoach.stripe_secret_key` | Stripe secret key (`sk_test_...` or `sk_live_...`) | For Stripe payments | https://dashboard.stripe.com/apikeys |
| `encoach.stripe_webhook_secret` | Stripe webhook signing secret (`whsec_...`) | For webhooks | https://dashboard.stripe.com/webhooks |

### PayPal (Payments)

Used by: Subscription checkout.

| Parameter | Description | Required | Where to Get |
|-----------|-------------|----------|-------------|
| `encoach.paypal_client_id` | PayPal REST API Client ID | For PayPal payments | https://developer.paypal.com/dashboard/applications |
| `encoach.paypal_client_secret` | PayPal REST API Client Secret | For PayPal payments | Same as above |

### Paymob (Payments)

Used by: Subscription checkout (Middle East region).

| Parameter | Description | Required | Where to Get |
|-----------|-------------|----------|-------------|
| `encoach.paymob_api_key` | Paymob API key | For Paymob payments | https://accept.paymob.com/portal2/en/settings |

---

## Which Keys Are Needed for What

| Feature | Keys Required |
|---------|--------------|
| User registration & login | `jwt_secret` |
| Generate reading/listening/writing/speaking exams | `openai_api_key` |
| Grade writing answers | `openai_api_key` |
| Grade speaking answers | `openai_api_key` |
| Generate listening audio (MP3) | `aws_access_key_id` + `aws_secret_access_key` |
| Transcribe audio (Whisper) | `openai_api_key` |
| Generate speaking avatar video | `elai_token` |
| Detect AI-generated content | `gptzero_api_key` |
| Personalised training tips | `openai_api_key` |
| Stripe payments | `stripe_secret_key` + `stripe_webhook_secret` |
| PayPal payments | `paypal_client_id` + `paypal_client_secret` |
| Paymob payments | `paymob_api_key` |

---

## Minimum Setup (to test AI features)

For basic AI testing, you only need **one key**:

```bash
cd /Users/yamenahmad/projects2026/odoo/odoo19/odoo
../.conda-envs/odoo19/bin/python odoo-bin shell -c ../odoo.conf -d encoach <<'EOF'
env['ir.config_parameter'].sudo().set_param('encoach.openai_api_key', 'sk-your-openai-key')
env.cr.commit()
print("OpenAI key set.")
EOF
```

This enables: exam generation, writing evaluation, speaking evaluation (text grading), short-answer grading, and training tips.

Add AWS keys later for listening audio, ELAI for avatar videos, and payment keys when ready for subscriptions.