Upload 11 files

.gitignore

@@ -0,0 +1,39 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual Environment
+venv/
+ENV/
+.env
+
+# Audio files
+audio_files/
+
+# IDE specific files
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS specific files
+.DS_Store
+Thumbs.db 

Dockerfile

@@ -0,0 +1,30 @@
+FROM python:3.9-slim
+
+WORKDIR /code
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements and install Python dependencies
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy application code
+COPY . .
+
+# Create directories for audio files
+RUN mkdir -p audio_files
+
+# Expose port
+EXPOSE 7860
+
+# Set environment variables
+ENV BACKEND_HOST=0.0.0.0
+ENV BACKEND_PORT=7860
+ENV BASE_URL=https://${SPACE_ID}.hf.space
+
+# Run the application
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"] 

README.md

@@ -1,11 +1,61 @@
----
-title: RAWI Story Generator
-emoji: 👁
-colorFrom: yellow
-colorTo: indigo
-sdk: docker
-pinned: false
-license: mit
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# رَاوي (Rawi) - منصة القص العربي بالذكاء الاصطناعي 
+
+## نظرة عامة
+خدمة API لتوليد قصص عربية تفاعلية باستخدام الذكاء الاصطناعي. تتيح المنصة للمستخدمين إنشاء قصص مخصصة بناءً على معلمات محددة، والتفاعل مع القصة من خلال خيارات متعددة، والاستماع إلى القصص المنشأة بتقنية تحويل النص إلى كلام.
+
+## المميزات
+- إنشاء قصص عربية أصلية باستخدام نماذج الذكاء الاصطناعي من DeepSeek
+- تخصيص معلمات القصة مثل الطول والنوع والشخصيات
+- القص التفاعلي مع خيارات متعددة للمسارات
+- تحويل النص إلى صوت عربي
+- واجهة برمجة تطبيقات RESTful متكاملة
+
+## واجهة برمجة التطبيقات (API)
+
+### تهيئة قصة جديدة
+```
+POST /api/stories/initialize
+```
+
+### متابعة القصة
+```
+POST /api/stories/continue
+```
+
+### تحويل القصة إلى صوت
+```
+POST /api/stories/tts
+```
+
+### تعديل القصة
+```
+POST /api/stories/edit
+```
+
+### الحصول على القصة كاملة
+```
+GET /api/stories/story/{story_id}
+```
+
+### الوصول إلى الملفات الصوتية
+```
+GET /audio/{filename}
+```
+
+## المتطلبات البيئية
+- `DEEPSEEK_API_KEY`: مفتاح API للوصول إلى نماذج DeepSeek
+- `BACKEND_HOST`: مضيف الخادم (افتراضي: 0.0.0.0)
+- `BACKEND_PORT`: منفذ الخادم (افتراضي: 7860)
+- `BASE_URL`: عنوان URL الأساسي للخدمة
+- `AUDIO_STORAGE_PATH`: مسار تخزين الملفات الصوتية (افتراضي: ./audio_files)
+
+## التكامل مع التطبيقات
+تم تصميم هذه الخدمة للعمل مع:
+1. واجهة المستخدم الويب لـراوي
+2. تطبيق Flutter للأجهزة المحمولة
+
+## توثيق واجهة برمجة التطبيقات
+يمكن الوصول إلى وثائق API التفاعلية الكاملة عبر:
+```
+https://[your-space-name].hf.space/docs
+``` 

ai_service.py

@@ -0,0 +1,508 @@
+import os
+import json
+import re
+import time
+import asyncio
+from typing import Dict, List, Tuple, Optional
+import httpx
+from dotenv import load_dotenv
+
+from models import StoryConfig, StoryParagraph, StoryChoice, StoryResponse
+from prompts import (
+    get_system_prompt, 
+    create_story_init_prompt, 
+    create_continuation_prompt,
+    create_title_prompt,
+    get_story_length_instructions
+)
+
+# تحميل المتغيرات البيئية
+load_dotenv()
+
+# الحصول على مفتاح API من المتغيرات البيئية
+DEEPSEEK_API_KEY = os.getenv("DEEPSEEK_API_KEY")
+DEEPSEEK_API_URL = "https://api.deepseek.com/v1/chat/completions"
+
+# تخزين سياق القصص
+# في نظام حقيقي، يجب استخدام قاعدة بيانات بدلاً من التخزين في الذاكرة
+stories_context = {}
+stories_metadata = {}
+
+
+async def generate_response(messages: List[Dict], retries=3, backoff_factor=1.5) -> str:
+    """
+    استدعاء DeepSeek API وتوليد استجابة بناءً على سلسلة الرسائل مع محاولة إعادة المحاولة في حالة الفشل
+    
+    Args:
+        messages: قائمة برسائل المحادثة
+        retries: عدد محاولات إعادة المحاولة في حالة فشل الاتصال (افتراضي: 3)
+        backoff_factor: معامل التأخير للمحاولات المتتالية (افتراضي: 1.5)
+        
+    Returns:
+        str: محتوى الاستجابة من API
+        
+    Raises:
+        Exception: في حالة فشل جميع المحاولات
+    """
+    if not DEEPSEEK_API_KEY:
+        raise Exception("مفتاح API غير متوفر. يرجى التحقق من إعداد المتغيرات البيئية.")
+        
+    headers = {
+        "Content-Type": "application/json",
+        "Authorization": f"Bearer {DEEPSEEK_API_KEY}"
+    }
+    
+    payload = {
+        "model": "deepseek-chat",  # استبدل باسم النموذج المناسب من DeepSeek API
+        "messages": messages,
+        "temperature": 0.7,
+        "max_tokens": 1000
+    }
+    
+    last_exception = None
+    
+    # محاولات إعادة الاتصال في حالة فشل API
+    for attempt in range(retries):
+        try:
+            async with httpx.AsyncClient() as client:
+                response = await client.post(
+                    DEEPSEEK_API_URL,
+                    headers=headers,
+                    json=payload,
+                    timeout=60.0
+                )
+                
+                if response.status_code == 429:  # Rate Limit
+                    # انتظار فترة قبل المحاولة مرة أخرى
+                    wait_time = backoff_factor * (2 ** attempt)
+                    print(f"تجاوز حد معدل الطلبات، انتظار {wait_time} ثانية قبل المحاولة مرة أخرى.")
+                    await asyncio.sleep(wait_time)
+                    continue
+                
+                if response.status_code != 200:
+                    error_msg = f"فشل طلب DeepSeek API: {response.status_code} - {response.text}"
+                    print(error_msg)
+                    last_exception = Exception(error_msg)
+                    
+                    # انتظار فترة قبل المحاولة مرة أخرى
+                    wait_time = backoff_factor * (2 ** attempt)
+                    await asyncio.sleep(wait_time)
+                    continue
+                
+                result = response.json()
+                if "choices" not in result or not result["choices"]:
+                    raise Exception("تنسيق استجابة DeepSeek API غير صالح")
+                    
+                return result["choices"][0]["message"]["content"]
+                
+        except httpx.HTTPError as e:
+            error_msg = f"خطأ في اتصال HTTP: {str(e)}"
+            print(error_msg)
+            last_exception = Exception(error_msg)
+            
+            # انتظار فترة قبل المحاولة مرة أخرى
+            wait_time = backoff_factor * (2 ** attempt)
+            await asyncio.sleep(wait_time)
+            continue
+            
+        except Exception as e:
+            error_msg = f"خطأ غير متوقع: {str(e)}"
+            print(error_msg)
+            last_exception = Exception(error_msg)
+            
+            # انتظار فترة قبل المحاولة مرة أخرى
+            wait_time = backoff_factor * (2 ** attempt)
+            await asyncio.sleep(wait_time)
+            continue
+    
+    # إذا وصلنا إلى هنا، فقد فشلت جميع المحاولات
+    raise last_exception or Exception("فشل الاتصال بـ DeepSeek API بعد عدة محاولات")
+
+
+def parse_paragraph_and_choices(response_text: str) -> Tuple[str, Optional[List[StoryChoice]]]:
+    """
+    تحليل استجابة النموذج واستخراج ��لفقرة والخيارات
+    """
+    # محاولة استخراج الفقرة
+    paragraph_match = re.search(r"الفقرة:(.*?)(?:الخيارات:|العنوان:|$)", response_text, re.DOTALL)
+    paragraph = paragraph_match.group(1).strip() if paragraph_match else response_text.strip()
+    
+    # محاولة استخراج الخيارات
+    choices = None
+    choices_match = re.search(r"الخيارات:(.*?)(?:$)", response_text, re.DOTALL)
+    
+    if choices_match:
+        choices_text = choices_match.group(1).strip()
+        choices = []
+        
+        # استخراج الخيارات المرقمة
+        for i, choice_match in enumerate(re.findall(r"\d+\.\s*(.*?)(?=\d+\.|$)", choices_text, re.DOTALL), 1):
+            choice_text = choice_match.strip()
+            if choice_text:
+                choices.append(StoryChoice(id=i, text=choice_text))
+        
+        # إذا لم يتم العثور على خيارات بالطريقة السابقة، نحاول طريقة أخرى
+        if not choices:
+            lines = choices_text.split("\n")
+            for i, line in enumerate([l for l in lines if l.strip()], 1):
+                if i <= 3:  # نقتصر على 3 خيارات
+                    # تجاهل الترقيم إذا كان موجوداً
+                    choice_text = re.sub(r"^\d+\.\s*", "", line).strip()
+                    choices.append(StoryChoice(id=i, text=choice_text))
+    
+    # استخراج العنوان إذا كان موجوداً
+    title = None
+    title_match = re.search(r"العنوان:(.*?)(?:$)", response_text, re.DOTALL)
+    if title_match:
+        title = title_match.group(1).strip()
+    
+    return paragraph, choices, title
+
+
+async def initialize_story(config: StoryConfig) -> StoryResponse:
+    """
+    بدء قصة جديدة باستخدام DeepSeek API
+    """
+    import uuid
+    story_id = str(uuid.uuid4())
+    
+    # إنشاء البرومبت الأولي
+    system_prompt = get_system_prompt()
+    user_prompt = create_story_init_prompt(config)
+    
+    messages = [
+        {"role": "system", "content": system_prompt},
+        {"role": "user", "content": user_prompt}
+    ]
+    
+    # استدعاء DeepSeek API
+    response_text = await generate_response(messages)
+    
+    # تحليل الاستجابة
+    paragraph_text, choices, _ = parse_paragraph_and_choices(response_text)
+    
+    # إنشاء فقرة القصة
+    paragraph = StoryParagraph(
+        content=paragraph_text,
+        choices=choices
+    )
+    
+    # حفظ سياق القصة
+    stories_context[story_id] = {
+        "paragraphs": [paragraph_text],
+        "current_paragraph": 1
+    }
+    
+    # حفظ معلومات القصة
+    length_info = get_story_length_instructions(config.length)
+    stories_metadata[story_id] = {
+        "config": config.dict(),
+        "max_paragraphs": length_info["paragraphs"],
+        "messages": messages + [{"role": "assistant", "content": response_text}],
+        "title": None
+    }
+    
+    # إنشاء استجابة القصة
+    story_response = StoryResponse(
+        story_id=story_id,
+        paragraph=paragraph,
+        is_complete=False
+    )
+    
+    return story_response
+
+
+async def continue_story(story_id: str, choice_id: int) -> StoryResponse:
+    """
+    متابعة القصة بناءً على اختيار المستخدم
+    """
+    if story_id not in stories_context or story_id not in stories_metadata:
+        raise ValueError("معرف القصة غير صالح")
+    
+    context = stories_context[story_id]
+    metadata = stories_metadata[story_id]
+    
+    # الحصول على سياق القصة والاختيار
+    paragraphs = context["paragraphs"]
+    current_paragraph = context["current_paragraph"]
+    max_paragraphs = metadata["max_paragraphs"]
+    
+    # الحصول على الرسائل السابقة
+    messages = metadata["messages"]
+    
+    # الحصول على نص الاختيار
+    last_message = messages[-1]["content"]
+    _, choices, _ = parse_paragraph_and_choices(last_message)
+    
+    if not choices or choice_id < 1 or choice_id > len(choices):
+        raise ValueError("معرف الاختيار غير صالح")
+    
+    choice_text = next((c.text for c in choices if c.id == choice_id), "")
+    
+    # إنشاء برومبت المتابعة
+    story_context_text = "\n".join(paragraphs)
+    continuation_prompt = create_continuation_prompt(
+        story_context_text, 
+        choice_id, 
+        choice_text, 
+        current_paragraph, 
+        max_paragraphs
+    )
+    
+    # إضافة رسالة المستخدم
+    messages.append({"role": "user", "content": continuation_prompt})
+    
+    # استدعاء DeepSeek API
+    response_text = await generate_response(messages)
+    
+    # تحليل الاستجابة
+    paragraph_text, choices, title = parse_paragraph_and_choices(response_text)
+    
+    # تحديث سياق القصة
+    paragraphs.append(paragraph_text)
+    context["current_paragraph"] += 1
+    context["paragraphs"] = paragraphs
+    
+    # تحديد ما إذا كانت القصة مكتملة
+    is_complete = current_paragraph >= max_paragraphs - 1
+    
+    # إذا كانت القصة مكتملة، احفظ العنوان
+    if is_complete and title:
+        metadata["title"] = title
+    
+    # تحديث الرسائل
+    messages.append({"role": "assistant", "content": response_text})
+    metadata["messages"] = messages
+    
+    # إنشاء فقرة القصة
+    paragraph = StoryParagraph(
+        content=paragraph_text,
+        choices=None if is_complete else choices
+    )
+    
+    # إنشاء استجابة القصة
+    story_response = StoryResponse(
+        story_id=story_id,
+        paragraph=paragraph,
+        is_complete=is_complete,
+        title=metadata["title"] if is_complete else None
+    )
+    
+    return story_response
+
+
+async def continue_story_with_text(story_id: str, custom_text: str) -> StoryResponse:
+    """
+    متابعة القصة بناءً على النص المخصص الذي أدخله المستخدم
+    """
+    print(f"continue_story_with_text called with story_id={story_id}, custom_text={custom_text}")
+    
+    if story_id not in stories_context or story_id not in stories_metadata:
+        print(f"Story ID {story_id} not found in context or metadata")
+        raise ValueError("معرف القصة غير صالح")
+    
+    context = stories_context[story_id]
+    metadata = stories_metadata[story_id]
+    
+    # الحصول على سياق القصة
+    paragraphs = context["paragraphs"]
+    current_paragraph = context["current_paragraph"]
+    max_paragraphs = metadata["max_paragraphs"]
+    
+    print(f"Story context: current_paragraph={current_paragraph}, max_paragraphs={max_paragraphs}")
+    
+    # الحصول على الرسائل السابقة
+    messages = metadata["messages"]
+    
+    # إنشاء برومبت المتابعة بالنص المخصص
+    story_context_text = "\n".join(paragraphs)
+    
+    # Create a prompt for continuing with custom text
+    custom_prompt = f"""
+لقد وصلنا إلى هذه النقطة في القصة:
+
+{story_context_text}
+
+المستخدم اختار أن يكتب رداً مخصصاً بدلاً من اختيار أحد الخيارات المقدمة. الرد المخصص للمستخدم هو:
+
+"{custom_text}"
+
+بناءً على هذا المدخل من المستخدم، استمر في القصة واكتب فقرة جديدة تأخذ بعين الاعتبار ما كتبه المستخدم.
+ثم قدم 3 خيارات جديدة للمستخدم ليختار منها للاستمرار في القصة.
+
+تذكر أن القصة الآن في:
+- الفقرة رقم: {current_paragraph} من {max_paragraphs}
+- إذا كانت هذه الفقرة الأخيرة أو قبل الأخيرة، قم بختم القصة بشكل مناسب.
+
+يجب أن يكون تنسيق ردك كما يلي:
+
+الفقرة: [نص الفقرة الجديدة من القصة]
+
+الخيارات:
+1. [الخيار الأول]
+2. [الخيار الثاني]
+3. [الخيار الثالث]
+
+إذا كانت هذه الفقرة الأخيرة، أضف عنواناً للقصة:
+
+العنوان: [عنوان مناسب للقصة كاملة]
+"""
+    
+    print(f"Custom prompt created, length: {len(custom_prompt)}")
+    
+    # إضافة رسالة المستخدم
+    messages.append({"role": "user", "content": custom_prompt})
+    
+    # استدعاء DeepSeek API
+    print("Calling DeepSeek API...")
+    response_text = await generate_response(messages)
+    print(f"DeepSeek API response received, length: {len(response_text)}")
+    
+    # تحليل الاستجابة
+    paragraph_text, choices, title = parse_paragraph_and_choices(response_text)
+    print(f"Parsed response: paragraph length={len(paragraph_text)}, choices={choices is not None}, title={title is not None}")
+    
+    # تحديث سياق القصة
+    paragraphs.append(paragraph_text)
+    context["current_paragraph"] += 1
+    context["paragraphs"] = paragraphs
+    
+    # تحديد ما إذا كانت القصة مكتملة
+    is_complete = current_paragraph >= max_paragraphs - 1
+    print(f"Is story complete: {is_complete}")
+    
+    # إذا كانت القصة مكتملة، احفظ العنوان
+    if is_complete and title:
+        metadata["title"] = title
+    
+    # تحديث الرسائل
+    messages.append({"role": "assistant", "content": response_text})
+    metadata["messages"] = messages
+    
+    # إنشاء فقرة القصة
+    paragraph = StoryParagraph(
+        content=paragraph_text,
+        choices=None if is_complete else choices
+    )
+    
+    # إنشاء استجابة القصة
+    story_response = StoryResponse(
+        story_id=story_id,
+        paragraph=paragraph,
+        is_complete=is_complete,
+        title=metadata["title"] if is_complete else None
+    )
+    
+    print(f"Story response created successfully")
+    return story_response
+
+
+async def get_complete_story(story_id: str) -> str:
+    """
+    الحصول على النص الكامل للقصة
+    """
+    if story_id not in stories_context:
+        raise ValueError("معرف القصة غير صالح")
+    
+    context = stories_context[story_id]
+    metadata = stories_metadata.get(story_id, {})
+    
+    story_text = "\n\n".join(context["paragraphs"])
+    
+    if metadata.get("title"):
+        # إضافة العنوان بصيغة صديقة لخدمة تحويل النص إلى كلام
+        story_text = f"قصة بعنوان {metadata['title']}.\n\n{story_text}"
+    
+    return story_text
+
+
+async def generate_title_if_missing(story_id: str) -> str:
+    """
+    توليد عنوان للقصة إذا لم يكن موجوداً
+    """
+    if story_id not in stories_metadata:
+        raise ValueError("معرف القصة غير صالح")
+        
+    metadata = stories_metadata[story_id]
+    
+    # إذا كان العنوان موجوداً بالفعل، أعده
+    if metadata.get("title"):
+        return metadata["title"]
+    
+    # توليد العنوان
+    complete_story = await get_complete_story(story_id)
+    
+    system_prompt = get_system_prompt()
+    title_prompt = create_title_prompt(complete_story)
+    
+    messages = [
+        {"role": "system", "content": system_prompt},
+        {"role": "user", "content": title_prompt}
+    ]
+    
+    title = await generate_response(messages)
+    
+    # تنظيف العنوان
+    title = title.strip().replace("العنوان:", "").strip()
+    
+    # حفظ العنوان
+    metadata["title"] = title
+    
+    return title
+
+async def edit_story(story_id: str, edit_instructions: str) -> dict:
+    """
+    تعديل القصة بناءً على تعليمات المستخدم
+    """
+    if story_id not in stories_context or story_id not in stories_metadata:
+        raise ValueError("معرف القصة غير صالح")
+    
+    # الحصول على نص القصة الكامل
+    paragraphs = stories_context[story_id]["paragraphs"]
+    complete_story = "\n".join(paragraphs)
+    
+    # إنشاء برومبت للتعديل
+    system_prompt = """أنت مساعد ذكي متخصص في تحرير وتعديل القصص العربية. مهمتك هي تعديل القصة بناءً على تعليمات المستخدم مع الحفاظ على الأسلوب والنبرة الأصلية. 
+قم بإرجاع القصة المعدلة بالكامل وليس فقط الأجزاء المعدلة. تأكد من تقسيم القصة إلى فقرات واضحة كما في النص الأصلي.
+إذا تطلبت التعليمات تغيير العنوان، قم بإضافة سطر "العنوان الجديد: <العنوان المعدل>" في بداية استجابتك."""
+    
+    user_prompt = f"""فيما يلي قصة كاملة:
+    
+{complete_story}
+
+تعليمات التعديل:
+{edit_instructions}
+
+قم بتعديل القصة وفقًا للتعليمات المذكورة أعلاه وأرجع القصة المعدلة بالكامل مقسمة إلى فقرات.
+"""
+    
+    messages = [
+        {"role": "system", "content": system_prompt},
+        {"role": "user", "content": user_prompt}
+    ]
+    
+    # استدعاء DeepSeek API
+    response_text = await generate_response(messages)
+    
+    # تحليل النص واستخراج العنوان الجديد إذا وجد
+    new_title = None
+    title_match = re.search(r"العنوان الجديد:\s*(.*?)(?:\n|$)", response_text, re.IGNORECASE)
+    if title_match:
+        new_title = title_match.group(1).strip()
+        response_text = re.sub(r"العنوان الجديد:\s*.*?(?:\n|$)", "", response_text, flags=re.IGNORECASE)
+    
+    # تقسيم النص المعدل إلى فقرات
+    edited_paragraphs = [p.strip() for p in response_text.split("\n\n") if p.strip()]
+    
+    # تحديث القصة في التخزين
+    stories_context[story_id]["paragraphs"] = edited_paragraphs
+    
+    # تحديث العنوان إذا كان هناك عنوان جديد
+    if new_title:
+        stories_metadata[story_id]["title"] = new_title
+    
+    # إرجاع البيانات المعدلة
+    return {
+        "paragraphs": edited_paragraphs,
+        "title": new_title or stories_metadata[story_id].get("title")
+    }

app.py

@@ -0,0 +1,8 @@
+"""
+Entry point for Hugging Face Spaces deployment of Rawi API
+"""
+
+from main import app
+
+# This file serves as the entry point for Hugging Face Spaces
+# It imports and exposes the FastAPI app object from main.py 

main.py

@@ -0,0 +1,112 @@
+"""
+راوي (Rawi) - Arabic AI Storytelling Platform
+Main application file for FastAPI server
+"""
+
+import os
+import sys
+import uvicorn
+import logging
+from fastapi import FastAPI, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from dotenv import load_dotenv
+from fastapi.responses import FileResponse
+from fastapi.staticfiles import StaticFiles
+from pathlib import Path
+
+# Add the current directory to Python path to enable imports
+sys.path.append(os.path.dirname(os.path.abspath(__file__)))
+
+# Import application routers
+from routers import story
+
+# ======== Configure Logging ========
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+# ======== Load Environment Variables ========
+load_dotenv()
+
+# ======== Server Configuration ========
+HOST = os.getenv("BACKEND_HOST", "0.0.0.0")
+PORT = int(os.getenv("BACKEND_PORT", "7860"))  # Updated default port for Hugging Face
+BASE_URL = os.getenv("BASE_URL", f"http://{HOST}:{PORT}")
+AUDIO_STORAGE_PATH = os.path.abspath(os.getenv("AUDIO_STORAGE_PATH", "./audio_files"))
+
+# DeepSeek API Key check
+DEEPSEEK_API_KEY = os.getenv("DEEPSEEK_API_KEY")
+
+# Log server settings
+logger.info(f"Server settings:")
+logger.info(f"Host: {HOST}")
+logger.info(f"Port: {PORT}")
+logger.info(f"Base URL: {BASE_URL}")
+logger.info(f"Audio storage path: {AUDIO_STORAGE_PATH}")
+logger.info(f"DeepSeek API Key set: {bool(DEEPSEEK_API_KEY)}")
+
+# ======== Ensure Audio Storage Directory Exists ========
+try:
+    Path(AUDIO_STORAGE_PATH).mkdir(parents=True, exist_ok=True)
+    logger.info(f"Created/verified audio storage directory at: {AUDIO_STORAGE_PATH}")
+except Exception as e:
+    logger.error(f"Error creating audio storage directory: {str(e)}")
+    raise
+
+# ======== Initialize FastAPI Application ========
+app = FastAPI(
+    title="راوي API",
+    description="واجهة برمجة تطبيقات لمنصة راوي لتوليد القصص العربية باستخدام الذكاء الاصطناعي",
+    version="1.0.0"
+)
+
+# ======== Configure CORS ========
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],  # In production, specify allowed origins instead of "*"
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# ======== Mount Static Files ========
+app.mount("/audio", StaticFiles(directory=AUDIO_STORAGE_PATH), name="audio")
+
+# ======== Register Routers ========
+app.include_router(story.router, prefix="/api/stories", tags=["قصص"])
+
+# ======== API Endpoints ========
+@app.get("/", tags=["الرئيسية"])
+async def root():
+    """
+    Root endpoint for the API
+    """
+    return {
+        "message": "مرحباً بك في واجهة برمجة تطبيقات راوي",
+        "docs": f"{BASE_URL}/docs"
+    }
+
+@app.get("/health", tags=["الحالة"])
+async def health_check():
+    """
+    Health check endpoint to verify API configuration
+    """
+    health_status = {
+        "status": "healthy",
+        "deepseek_api": bool(DEEPSEEK_API_KEY),
+        "audio_storage": os.path.exists(AUDIO_STORAGE_PATH),
+    }
+    
+    if not DEEPSEEK_API_KEY:
+        health_status["status"] = "degraded"
+        health_status["message"] = "DeepSeek API key is not set. Story generation will not work."
+        
+    return health_status
+
+# ======== Run Application ========
+if __name__ == "__main__":
+    uvicorn.run(
+        "main:app",
+        host=HOST,
+        port=PORT,
+        reload=True  # Disable in production for better performance
+    )

models.py

@@ -0,0 +1,107 @@
+"""
+راوي (Rawi) - Arabic AI Storytelling Platform
+Data models for API requests and responses
+"""
+
+from enum import Enum
+from typing import List, Optional
+from pydantic import BaseModel, Field
+
+
+# ======== Enum Types ========
+
+class StoryLength(str, Enum):
+    """Story length options"""
+    SHORT = "short"
+    MEDIUM = "medium"
+    LONG = "long"
+
+
+class StoryType(str, Enum):
+    """Story genre options in Arabic"""
+    ROMANCE = "رومانسي"
+    HORROR = "رعب"
+    COMEDY = "كوميدي"
+    ACTION = "أكشن"
+    ADVENTURE = "مغامرة"
+    DRAMA = "دراما"
+    FANTASY = "خيال"
+    HISTORICAL = "تاريخي"
+    MYSTERY = "غموض"
+    NONE = "لا"
+
+
+class CharacterGender(str, Enum):
+    """Character gender options in Arabic"""
+    MALE = "ذكر"
+    FEMALE = "أنثى"
+
+
+# ======== Request Models ========
+
+class Character(BaseModel):
+    """Character information for story generation"""
+    name: str = Field(..., description="اسم الشخصية")
+    gender: CharacterGender = Field(..., description="جنس الشخصية")
+    description: str = Field(..., description="وصف الشخصية")
+
+
+class StoryConfig(BaseModel):
+    """Configuration for initial story generation"""
+    length: StoryLength = Field(..., description="طول القصة")
+    primary_type: StoryType = Field(..., description="النوع الأساسي للقصة")
+    secondary_type: StoryType = Field(default=StoryType.NONE, description="النوع الثانوي للقصة")
+    characters: List[Character] = Field(default=[], description="الشخصيات في القصة")
+
+
+class ChoiceRequest(BaseModel):
+    """Request to continue a story with a choice or custom text"""
+    story_id: str = Field(..., description="معرف القصة")
+    choice_id: Optional[int] = Field(None, description="معرف الاختيار الذي تم اختياره")
+    custom_text: Optional[str] = Field(None, description="النص المخصص الذي أدخله المستخدم")
+
+
+class TTSRequest(BaseModel):
+    """Request to generate text-to-speech for a story"""
+    story_id: str = Field(..., description="معرف القصة")
+    speed: float = Field(1.0, description="سرعة الصوت (0.5 للبطيء، 1.0 للعادي، 2.0 للسريع)", ge=0.5, le=2.0)
+
+
+class EditRequest(BaseModel):
+    """Request to edit a story based on user instructions"""
+    story_id: str = Field(..., description="معرف القصة")
+    edit_instructions: str = Field(..., description="تعليمات لتعديل القصة")
+
+
+# ======== Response Models ========
+
+class StoryChoice(BaseModel):
+    """A choice option presented to the user"""
+    id: int = Field(..., description="معرف الاختيار")
+    text: str = Field(..., description="نص الاختيار")
+
+
+class StoryParagraph(BaseModel):
+    """A paragraph of story content with optional choices"""
+    content: str = Field(..., description="محتوى الفقرة")
+    choices: Optional[List[StoryChoice]] = Field(default=None, description="الاختيارات المتاحة بعد هذه الفقرة")
+
+
+class StoryResponse(BaseModel):
+    """Response containing story content and metadata"""
+    story_id: str = Field(..., description="معرف القصة")
+    paragraph: StoryParagraph = Field(..., description="فقرة من القصة")
+    is_complete: bool = Field(default=False, description="هل القصة اكتملت؟")
+    title: Optional[str] = Field(default=None, description="عنوان القصة (يتم إضافته عند اكتمال القصة)")
+
+
+class TTSResponse(BaseModel):
+    """Response containing URL to audio file"""
+    audio_url: str = Field(..., description="رابط ملف الصوت")
+
+
+class EditResponse(BaseModel):
+    """Response containing edited story content"""
+    success: bool = Field(default=True, description="نجاح عملية التعديل")
+    paragraphs: List[str] = Field(..., description="فقرات القصة المعدلة")
+    title: Optional[str] = Field(default=None, description="عنوان القصة المعدل (اختياري)")

prompts.py

@@ -0,0 +1,189 @@
+from typing import List, Dict, Any
+from models import StoryLength, StoryType, Character, StoryConfig
+
+
+def get_system_prompt() -> str:
+    """
+    الحصول على برومبت النظام الأساسي الذي يحدد سلوك نموذج الذكاء الاصطناعي
+    """
+    return """
+    You are a professional and creative Arabic story writer. Your task is to write original, engaging, and cohesive Arabic stories.
+    
+    Adhere to the following standards in all the stories you write:
+
+    1. Use correct and understandable classical Arabic language, free from grammatical and spelling errors.
+    2. Build a coherent and logical story that follows good dramatic structure principles (beginning, rising action, climax, resolution).
+    3. Adhere to Arabic and Islamic values and ethics in the story content.
+    4. Avoid inappropriate content or anything that violates public taste or religious values.
+    5. Provide detailed sensory descriptions of characters, places, and events to make the story vivid and engaging.
+    6. Make dialogue realistic and natural, appropriate to the story's characters and environment.
+    7. Maintain consistency in character traits and behaviors throughout the story.
+    8. Include positive values and useful lessons in an indirect way.
+    9. Use diverse narrative techniques: description, dialogue, narration, internal monologue.
+    10. Create a clear conflict that drives the story events and maintains reader interest.
+
+    Each time you are asked to write a new paragraph of the story, you must:
+    - Write a coherent and engaging narrative paragraph of 4-6 lines in Arabic.
+    - Provide 3 distinctive and interesting options to develop the story's path.
+    
+    Important rules for options:
+    1. Make options very practical and short (3-5 words only) in Arabic.
+    2. ALWAYS start each option with the character's name followed by the action verb.
+    3. Use clear format: "[Character name] + verb", for example: "أحمد يتصل بالشرطة" (Ahmed calls the police), "سارة تهرب من المكان" (Sarah escapes from the place).
+    4. Make it absolutely clear WHO is performing the action in each option.
+    5. Don't explain what will happen after the choice, just mention the direct action.
+    6. Ensure each option will lead to a completely different path in the story.
+    7. Make options logical and appropriate to the current situation in the story.
+    
+    Result of user choice:
+    1. Do not summarize the user's chosen option at the beginning of the next paragraph.
+    2. Start directly with the reactions and consequences resulting from the user's choice.
+    3. Present surprising and unexpected developments resulting from the choice.
+    4. Maintain story consistency despite the change in path.
+    
+    When the story is complete, choose an engaging and deep title that reflects the essence and content of the story.
+    """
+
+
+def format_characters_info(characters: List[Character]) -> str:
+    """
+    تنسيق معلومات الشخصيات لتضمينها في البرومبت
+    """
+    if not characters:
+        return "لا توجد شخصيات محددة، يمكنك إنشاء شخصيات مناسبة للقصة."
+    
+    characters_info = "معلومات الشخصيات:\n"
+    for i, character in enumerate(characters, 1):
+        gender_text = "ذكر" if character.gender.value == "ذكر" else "أنثى"
+        characters_info += f"{i}. الشخصية: {character.name}، الجنس: {gender_text}، الوصف: {character.description}\n"
+    
+    return characters_info
+
+
+def get_story_length_instructions(length: StoryLength) -> Dict[str, Any]:
+    """
+    الحصول على تعليمات طول القصة وعدد الفقرات
+    """
+    length_mapping = {
+        StoryLength.SHORT: {"paragraphs": 3, "description": "قصة قصيرة تتكون من 3 فقرات"},
+        StoryLength.MEDIUM: {"paragraphs": 5, "description": "قصة متوسطة الطول تتكون من 5 فقرات"},
+        StoryLength.LONG: {"paragraphs": 7, "description": "قصة طويلة تتكون من 7 فقرات"}
+    }
+    
+    return length_mapping.get(length, length_mapping[StoryLength.MEDIUM])
+
+
+def get_story_type_description(primary_type: StoryType, secondary_type: StoryType) -> str:
+    """
+    الحصول على وصف نوع القصة
+    """
+    if secondary_type == StoryType.NONE:
+        return f"قصة من نوع {primary_type.value}"
+    else:
+        return f"قصة تجمع بين نوعي {primary_type.value} و{secondary_type.value}"
+
+
+def create_story_init_prompt(config: StoryConfig) -> str:
+    """
+    إنشاء البرومبت الأولي لبدء القصة
+    """
+    length_info = get_story_length_instructions(config.length)
+    story_type = get_story_type_description(config.primary_type, config.secondary_type)
+    characters_info = format_characters_info(config.characters)
+    
+    prompt = f"""
+    Please write {length_info['description']} of {story_type}.
+    
+    {characters_info}
+    
+    Required from you:
+    1. Write the first paragraph of the story (4-6 lines) in Arabic.
+    2. Start the story with a strong and engaging beginning that captivates the reader from the first line.
+    3. Present the characters and setting (place and time) clearly and interestingly.
+    4. Establish a conflict, problem, or situation that drives the story events.
+    5. Present 3 short, exciting, and logical options for actions the protagonist can take.
+    6. Make the options very short (3-5 words only) and practical and direct.
+    7. ALWAYS include the character's name in each option before the action verb.
+    8. Format: "[Character name] + verb", like: "أحمد يتصل بالشرطة", "سارة تهرب من المكان".
+    
+    Present the first paragraph and options in the following format:
+    
+    الفقرة:
+    [Write the first paragraph of the story here in Arabic]
+    
+    الخيارات:
+    1. [Character name + action verb in Arabic, 3-5 words total]
+    2. [Character name + different action verb in Arabic, 3-5 words total]
+    3. [Character name + another different action verb in Arabic, 3-5 words total]
+    """
+    
+    return prompt
+
+
+def create_continuation_prompt(story_context: str, choice_id: int, choice_text: str, current_paragraph: int, max_paragraphs: int) -> str:
+    """
+    إنشاء برومبت لاستكمال القصة بناءً على اختيار المستخدم
+    """
+    is_final = current_paragraph >= max_paragraphs - 1
+    
+    prompt = f"""
+    Story context so far:
+    {story_context}
+    
+    The user chose path number {choice_id}: {choice_text}
+    
+    Required from you:
+    1. Continue writing the story with a new paragraph (4-6 lines) in Arabic that directly follows the choice made by the user.
+    2. Do not summarize the choice that the user made; instead, start directly with the events that result from this choice.
+    3. Add unexpected and exciting developments to engage the reader.
+    4. Maintain consistency in the story's characters and world.
+    """
+    
+    if is_final:
+        prompt += """
+    5. This is the final paragraph of the story, so end the story in a logical and satisfying way that closes all open paths.
+    6. Suggest an appropriate and deep title for the complete story.
+    
+    Present the final paragraph and title in the following format:
+    
+    الفقرة:
+    [Write the final paragraph of the story here in Arabic]
+    
+    العنوان:
+    [Write the suggested title for the story here in Arabic]
+    """
+    else:
+        prompt += """
+    5. Present 3 short, logical, and practical options for continuing the story.
+    6. Make the options very short (3-5 words only) in Arabic.
+    7. ALWAYS include the character's name in each option before the action verb.
+    8. Format: "[Character name] + verb", like: "أحمد يتصل بالشرطة", "سارة تهرب من المكان".
+    9. Make it absolutely clear WHO is performing the action in each option.
+    10. Ensure each option will lead to a completely different path in the story.
+    
+    Present the next paragraph and options in the following format:
+    
+    الفقرة:
+    [Write the next paragraph of the story here in Arabic]
+    
+    الخيارات:
+    1. [Character name + action verb in Arabic, 3-5 words total]
+    2. [Character name + different action verb in Arabic, 3-5 words total]
+    3. [Character name + another different action verb in Arabic, 3-5 words total]
+    """
+    
+    return prompt
+
+
+def create_title_prompt(complete_story: str) -> str:
+    """
+    إنشاء برومبت لتوليد عنوان مناسب للقصة المكتملة
+    """
+    return f"""
+    Here is a complete story:
+    
+    {complete_story}
+    
+    Suggest an appropriate and engaging title for this story that reflects its essence and content.
+    Provide only the title without any additional explanation and without any story Characters names in Arabic.
+    """

requirements.txt

@@ -0,0 +1,9 @@
+fastapi==0.110.0
+uvicorn==0.28.0
+pydantic==2.6.1
+python-dotenv==1.0.1
+httpx==0.26.0
+gTTS==2.5.0
+python-multipart==0.0.9
+starlette==0.36.3
+aiofiles==23.2.1

tts_service.py

@@ -0,0 +1,132 @@
+import os
+import asyncio
+import re
+from gtts import gTTS
+import uuid
+import json
+from pathlib import Path
+from dotenv import load_dotenv
+
+from ai_service import get_complete_story, generate_title_if_missing
+
+# تحميل المتغيرات البيئية
+load_dotenv()
+
+# الحصول على مسار تخزين ملفات الصوت
+AUDIO_STORAGE_PATH = os.path.abspath(os.getenv("AUDIO_STORAGE_PATH", "./audio_files"))
+BASE_URL = os.getenv("BASE_URL", "http://localhost:8000")
+
+# قاموس لتخزين معرفات الملفات الصوتية للقصص
+story_audio_files = {}
+
+def clean_text_for_tts(text: str) -> str:
+    """
+    تنظيف النص من الرموز التي قد تؤثر على جودة القراءة الصوتية
+    """
+    # استبدال علامات الترقيم التي قد تسبب مشاكل بمسافات أو استبعادها
+    text = re.sub(r'!', ' ', text)  # استبدال علامة التعجب بمسافة
+    text = re.sub(r'\?', ' ', text)  # استبدال علامة الاستفهام بمسافة
+    text = re.sub(r'[،,]', ' ', text)  # استبدال الفواصل بمسافات
+    text = re.sub(r';', ' ', text)  # استبدال الفاصلة المنقوطة بمسافة
+    text = re.sub(r':', ' ', text)  # استبدال النقطتين بمسافة
+    text = re.sub(r'#', ' ', text)  # استبدال علامة الهاشتاغ بمسافة
+    text = re.sub(r'@', ' ', text)  # استبدال علامة الإيميل بمسافة
+    text = re.sub(r'_', ' ', text)  # استبدال الشرطة السفلية بمسافة
+    text = re.sub(r'\*', ' ', text)  # استبدال علامة النجمة بمسافة
+    text = re.sub(r'=', ' ', text)  # استبدال علامة المساواة بمسافة
+    text = re.sub(r'\+', ' ', text)  # استبدال علامة الزائد بمسافة
+    text = re.sub(r'-', ' ', text)  # استبدال علامة الناقص بمسافة
+    text = re.sub(r'/', ' ', text)  # استبدال علامة القسمة بمسافة
+    text = re.sub(r'\\', ' ', text)  # استبدال الشرطة المائلة العكسية بمسافة
+    text = re.sub(r'%', ' بالمئة ', text)  # استبدال علامة النسبة بكلمة "بالمئة"
+    text = re.sub(r'&', ' و ', text)  # استبدال علامة & بكلمة "و"
+    text = re.sub(r'\^', ' ', text)  # استبدال علامة القوة بمسافة
+    text = re.sub(r'\$', ' ', text)  # استبدال علامة الدولار بمسافة
+    
+    # إزالة علامات التنصيص تماماً
+    text = re.sub(r'["""\'«»]', ' ', text)  # إزالة كل أنواع علامات التنصيص
+    
+    # إزالة الأقواس والمحتوى بداخلها
+    text = re.sub(r'\(.*?\)', ' ', text)
+    text = re.sub(r'\[.*?\]', ' ', text)
+    text = re.sub(r'\{.*?\}', ' ', text)
+    text = re.sub(r'<.*?>', ' ', text)
+    
+    # تنظيف الفترات الطويلة من المسافات المتكررة الناتجة عن الإزالة
+    text = re.sub(r'\s+', ' ', text)
+    
+    # الحفاظ على النقاط كفواصل بين الجمل مع إضافة مسافة
+    text = re.sub(r'\.', '. ', text)
+    
+    return text.strip()
+
+async def ensure_storage_path():
+    """
+    التأكد من وجود مجلد لتخزين ملفات الصوت
+    """
+    Path(AUDIO_STORAGE_PATH).mkdir(parents=True, exist_ok=True)
+
+async def text_to_speech(text: str, filename: str) -> str:
+    """
+    تحويل النص إلى صوت وحفظه في ملف
+    """
+    # التأكد من وجود مجلد التخزين
+    await ensure_storage_path()
+    
+    # مسار الملف الكامل
+    file_path = os.path.join(AUDIO_STORAGE_PATH, filename)
+    
+    # التحقق مما إذا كان الملف موجوداً بالفعل
+    if os.path.exists(file_path):
+        return filename
+    
+    # تنظيف النص من الرموز التي قد تؤثر على جودة القراءة
+    cleaned_text = clean_text_for_tts(text)
+    print(f"Original text length: {len(text)}, Cleaned text length: {len(cleaned_text)}")
+    
+    # استخدام وظيفة run_in_executor لتنفيذ عملية TTS في خيط منفصل
+    loop = asyncio.get_event_loop()
+    
+    await loop.run_in_executor(
+        None,
+        lambda: gTTS(text=cleaned_text, lang='ar', slow=False).save(file_path)
+    )
+    
+    return filename
+
+async def generate_audio_for_story(story_id: str, speed: float = 1.0) -> str:
+    """
+    توليد ملف صوتي للقصة الكاملة وإرجاع معرف الملف مع معلومات السرعة
+    """
+    # التحقق مما إذا كان هناك ملف صوتي موجود للقصة
+    if story_id not in story_audio_files:
+        # التأكد من وجود عنوان للقصة
+        await generate_title_if_missing(story_id)
+        
+        # الحصول على نص القصة الكامل
+        story_text = await get_complete_story(story_id)
+        
+        # إنشاء اسم فريد للملف الصوتي
+        filename = f"{story_id}_{uuid.uuid4().hex}.mp3"
+        
+        # تحويل النص إلى صوت
+        await text_to_speech(story_text, filename)
+        
+        # تخزين معرف الملف الصوتي للقصة
+        story_audio_files[story_id] = filename
+    
+    # إضافة معلومات السرعة للملف (سيتم استخدامها في الواجهة الأمامية)
+    # وذلك حتى نتجنب الحاجة إلى معالجة ملفات الصوت مباشرةً
+    filename = story_audio_files[story_id]
+    
+    return filename
+
+def get_audio_url(filename: str, speed: float = 1.0) -> str:
+    """
+    الحصول على رابط الملف الصوتي مع معلومات السرعة
+    """
+    base_url = f"{BASE_URL}/audio/{filename}"
+    
+    # إضافة معامل سرعة التشغيل كمعامل استعلام
+    # سيتم استخدامه في الواجهة الأمامية لضبط سرعة التشغيل
+    return f"{base_url}?speed={speed}"