I want to create a playground for researcher, it is like their notebooks of different topics. 
available at: /playground 
only for subscribed users (check readme how to check if a user is subscribed)
follow the website style. 
- use mainly Azure OpenAI gpt endpoint, put variables in env for keys and endpoint
- use async call to wait for user requests, if it takes too long, users can exit the page and come back later.
- suggest system prompt to help users write related research and summarize a given research topic.
- When users write the title of the project, call LLM to suggest a few keywords for their work, allow them to add modify or remove the main research keywords.
- User keywords for retrieving relevant researches.
- allow a chat in the side so users can ask for specific thing.
- Any moment users can select a text in their notebook, once selected, a popup will appear to ask LLM about it.
- The response from the LLM can be added to the notebook (there will be insert button in the popup to the notebook or ignore)

---

# Playground AI Service - Implementation Status

## ✅ Completed Features

### 1. Core Features
- **Multi-Source Academic RAG** - Search Shamra Library, arXiv, and Web
- **Academic Translation Suite** - With specialized personas (scientific, medical, legal, technical)
- **Intelligent Writing Canvas** - Project creation, editing, keywords management
- **Write with AI** - RAG-powered content generation with citations
- **Text Processing** - Rephrase, proofread, criticize, ask, translate
- **Tashkeel** - Arabic text vowelization
- **Citation Generator** - APA/MLA/Chicago formatting

### 2. Subscription System (NEW - Feb 2026)
- **Three Subscription Tiers:**
  - Basic ($4.99/mo) - PDF downloads only
  - Starter ($9/mo, 500 credits) - AI writing, rephrase, proofread
  - Researcher ($19/mo, 1500 credits) - All features + translation
- **Stripe Integration** - Payment processing with product IDs
- **Subscription Page** - Modern UI at `/subscription` with tier comparison

### 3. Usage Monitoring & Credits (NEW - Feb 2026)
- **Credit System** - Monthly credits per tier
- **Daily Limits** - Prevent abuse (50/day Starter, 150/day Researcher)
- **Usage Logging** - Track all API calls with tokens consumed
- **Admin Dashboard** - Monitor usage, costs, subscriptions at `/jim19ud83/playground`

### 4. Monthly Credit Reset (NEW - Feb 2026)
- **Lazy Reset** - Credits reset on first API call of new month
- **Login Reset** - Check and reset credits on user login
- **Cron Job** - Daily batch reset for inactive users
  ```bash
  0 0 * * * php bin/console app:reset-playground-credits
  ```

### 5. Stripe Webhook Integration (NEW - Feb 2026)
- **Payment Events:**
  - `invoice.payment_succeeded` - Activate/renew subscription
  - `invoice.payment_failed` - Deactivate subscription
  - `customer.subscription.deleted` - Cancel subscription
- **Automatic Renewal Detection** - Credits reset on renewal via `billing_reason`
- **Webhook Handler** - `/webhook` endpoint handles both legacy and Playground subscriptions

---

## Architecture Overview

```
┌──────────────────────────────────────────────────────────────────┐
│                        Controllers                                │
│  PlaygroundController | PlaygroundAPIController | Translation    │
├──────────────────────────────────────────────────────────────────┤
│                         Services                                  │
│  ┌────────────────────┐  ┌──────────────────┐  ┌──────────────┐  │
│  │ AzureOpenAIService │  │ PlaygroundRAG    │  │ ProjectSvc   │  │
│  │ (AI Integration)   │  │ Service          │  │ (CRUD)       │  │
│  └────────────────────┘  └──────────────────┘  └──────────────┘  │
│  ┌────────────────────┐  ┌──────────────────┐  ┌──────────────┐  │
│  │ UsageMonitorSvc    │  │ Playground       │  │ Document     │  │
│  │ (Credits/Limits)   │  │ SubscriptionSvc  │  │ ParserSvc    │  │
│  └────────────────────┘  └──────────────────┘  └──────────────┘  │
├──────────────────────────────────────────────────────────────────┤
│                         Entities                                  │
│  PlaygroundProject | PlaygroundChat | PlaygroundNotebook          │
│  PlaygroundTranslation | PlaygroundSubscription | UsageLog        │
├──────────────────────────────────────────────────────────────────┤
│                    External Services                              │
│  Azure OpenAI | ElasticSearch | arXiv | Stripe | SerpAPI         │
└──────────────────────────────────────────────────────────────────┘
```

---

## Key Files

| File | Purpose |
|------|---------|
| `src/Controller/PlaygroundController.php` | UI routes |
| `src/Controller/PlaygroundAPIController.php` | REST API |
| `src/Service/Playground/AzureOpenAIService.php` | AI integration |
| `src/Service/Playground/UsageMonitorService.php` | Credit tracking |
| `src/Service/Playground/PlaygroundSubscriptionService.php` | Stripe webhooks |
| `src/Entity/PlaygroundSubscription.php` | User subscription entity |
| `src/Entity/PlaygroundUsageLog.php` | Usage tracking entity |
| `src/EventListener/PlaygroundCreditsLoginListener.php` | Login credit reset |
| `src/Command/ResetPlaygroundCreditsCommand.php` | Cron command |
| `templates/playground/` | UI templates |
| `config/routes/playground.yaml` | Route config |

---

## Environment Variables

```env
# Azure OpenAI
AZURE_OPENAI_ENDPOINT=https://xxx.openai.azure.com
AZURE_OPENAI_API_KEY=xxx
AZURE_OPENAI_DEPLOYMENT=gpt-4
AZURE_OPENAI_API_VERSION=2024-02-15-preview

# Stripe Products
STRIPE_PRODUCT_BASIC_MONTH=prod_TwCkOEdkLkZ9Cy
STRIPE_PRODUCT_BASIC_YEAR=prod_TwCnWyQ81l67U2
STRIPE_STARTER_MONTH=prod_TwD8mNJxZT8Ckq
STRIPE_STARTER_YEAR=prod_TwDCRjCF7vwSAl
STRIPE_RESEARCHER_MONTH=prod_TwDK3sM6ZIDslF
STRIPE_RESEARCHER_YEAR=prod_TwDMdQNHa5BsNn

# Debug
PLAYGROUND_DEBUG=false
```

---

## Subscription Tiers

| Tier | Monthly | Yearly | Credits/mo | Daily Limit | Translation | Duration |
|------|---------|--------|------------|-------------|-------------|----------|
| **Trial** | Free | — | 100 (one-time) | — | ✅ | 14 days |
| Basic | $4.99 | $49.99 | 0 | 0 | ❌ | — |
| Starter | $9 | $99 | 500 | 50 | ❌ | — |
| Researcher | $19 | $199 | 1500 | 150 | ✅ | — |

---

## Free Trial Activation

### How It Works
1. Non-subscribed users visiting `/playground` see a **promo/landing page** showcasing features.
2. The promo page has two CTA buttons:
   - **"Activate Free Demo"** → `GET /playground/activate-demo`
   - **"See Subscription Plans"** → subscription page
3. Clicking "Activate Free Demo" creates a `PlaygroundSubscription` row with:
   - `tier = 'trial'`
   - `monthly_credits = 100` (one-time, no reset)
   - `subscription_end = NOW() + 14 days`
   - `credits_reset_date = subscription_end` (prevents mid-trial reset)
   - `is_active = true`
   - `stripe_subscription_id = NULL`
4. User is immediately **redirected to the playground** and can start using all features.
5. A flash message confirms: _"Your free trial has been activated! You have 100 credits…"_

### One-Time Only
- Each user can activate the trial **once**. If a `PlaygroundSubscription` already exists for the user (trial or paid), clicking the button again redirects to the playground without creating a new record.

### Expiration
- On each playground visit, `isUserSubscribed()` checks `subscription_end`:
  - If `NOW() > subscription_end` → sets `is_active = false` and denies access.
  - User sees the promo page again and can subscribe to a paid plan.

### Access Check Flow (isUserSubscribed)
```
1. ROLE_ADMIN / ROLE_SUPER_ADMIN → always allowed
2. PlaygroundSubscription (trial/paid):
   a. Active + no end date → allowed (paid, ongoing)
   b. Active + end date in future → allowed (trial or term sub)
   c. Active + end date passed → deactivate & deny
3. Legacy AcademicSubscription → fallback check
```

### Key Files
| File | Change |
|------|--------|
| `PlaygroundSubscription.php` | Added `TIER_TRIAL = 'trial'` constant |
| `PlaygroundController.php` | Implemented `activateDemo()` with real logic; updated `isUserSubscribed()` to check `PlaygroundSubscription` + expiry |
| `subscribe_required.html.twig` | Promo page with feature list and CTA buttons |
| `Playground.en.yml` / `Playground.ar.yml` | Added `promo.trial_activated` translation |
| `config/routes/playground.yaml` | Route `playground_activate_demo` |

---

## Credit Costs

| Action | Credits |
|--------|---------|
| chat | 1 |
| rephrase | 1 |
| proofread | 1 |
| criticize | 1 |
| ask | 1 |
| translate | 2 |
| generate | 3 |
| tashkeel | 1 |
| keywords | 1 |

---

## Admin Access

- **Dashboard**: `/jim19ud83/playground`
- **Bypass**: ROLE_ADMIN and ROLE_SUPER_ADMIN have unlimited access

---

## ⏳ Pending / Future Work

1. **Enterprise Tier** - Custom pricing, SSO, unlimited credits
2. **Cost Monitoring** - Azure OpenAI token cost tracking
3. **Rate Limiting** - Additional DDoS protection
4. **Usage Analytics** - Detailed charts in admin dashboard
5. **Email Notifications** - Credit exhaustion warnings
6. **Overage Billing** - Pay-per-use beyond monthly credits

---

## Original Requirements (Reference)

1. Product Overview

Shamra Academia AI Playground is a high-end, research-focused workspace designed specifically for the Arabic-speaking academic market. It combines an Intelligent Writing Canvas with Multi-Source RAG (Retrieval-Augmented Generation) and a specialized Academic Translation Suite.

2. Core Features & Functional Requirements

2.1. Multi-Source Academic RAG

The platform must allow users to toggle between distinct data silos to ground AI responses in verified academic contexts.

Silo 1: Shamra Library: use the backbone mentioned in README file about retrieving relevant researches. 

Silo 2: arXiv Global: Real-time access to global pre-print research (primarily English).

Silo 3: General Web Search: Live web results for current events.

Requirement: AI responses must include citations and source attribution with timestamps.


2.2. Academic Translation Suite

A specialized mode for translating research papers between Arabic and English.

Dual-Pane UI: A side-by-side view where the source (RTL/Arabic) and target (LTR/English) are editable and visible simultaneously.

File Upload & Parsing: Support for .pdf, .docx, and .txt.

Technical Requirement: The system must extract raw text while attempting to preserve structural integrity (headers, paragraphs).

Context-Aware Translation: The engine must use "Academic Personas" to ensure terminology (e.g., "Deep Learning" vs. "التعلم العميق") is consistent with scientific standards rather than literal dictionary definitions.

2.3. Intelligent Writing Canvas

Dynamic Projects: Ability to start "New Projects" which clear the state and initialize a new context.

Academic Micro-Tools:

Tashkeel: Automatic vowelization of Arabic text.

Citation Generator: Automated formatting for APA/MLA based on chat findings.

Persistence: All data (editor content, translations, chat history) must be saved to the user's project profile.