Upload 2 files

app/services/hf_client.py

@@ -0,0 +1,103 @@
+"""
+خدمة الاتصال بنموذج Hugging Face عبر huggingface_hub InferenceClient.
+
+تدعم استدعاء نماذج LLM/Chatbot المستضافة على:
+- Hugging Face Inference API (المجاني/المدفوع)
+- Hugging Face Inference Endpoints (استضافة مخصصة)
+- مزودين خارجيين متوافقين (مثل together, fireworks-ai...) عبر بارامتر provider
+"""
+from __future__ import annotations
+
+import logging
+from collections.abc import AsyncGenerator
+
+from huggingface_hub import AsyncInferenceClient
+from huggingface_hub.errors import HfHubHTTPError
+
+from app.config import Settings
+from app.schemas import ChatMessage
+
+logger = logging.getLogger("hf_chat_backend.hf_client")
+
+
+class HFClientError(Exception):
+    """خطأ عام أثناء الاتصال بنموذج Hugging Face."""
+
+
+class HFInferenceService:
+    """طبقة عزل (Adapter) فوق huggingface_hub لسهولة الاستبدال أو الاختبار."""
+
+    def __init__(self, settings: Settings) -> None:
+        self._settings = settings
+        self._client = AsyncInferenceClient(
+            model=settings.hf_model_id,
+            token=settings.hf_api_token or None,
+            provider=settings.hf_provider,
+            timeout=settings.hf_timeout_seconds,
+        )
+
+    @staticmethod
+    def _to_hf_messages(messages: list[ChatMessage]) -> list[dict]:
+        return [{"role": m.role, "content": m.content} for m in messages]
+
+    async def chat_completion(
+        self,
+        messages: list[ChatMessage],
+        max_new_tokens: int | None = None,
+        temperature: float | None = None,
+        top_p: float | None = None,
+    ) -> tuple[str, str | None]:
+        """يرسل المحادثة كاملة للنموذج ويعيد الرد النهائي (بدون بث)."""
+        try:
+            completion = await self._client.chat_completion(
+                messages=self._to_hf_messages(messages),
+                max_tokens=max_new_tokens or self._settings.default_max_new_tokens,
+                temperature=(
+                    temperature
+                    if temperature is not None
+                    else self._settings.default_temperature
+                ),
+                top_p=top_p if top_p is not None else self._settings.default_top_p,
+                stream=False,
+            )
+            choice = completion.choices[0]
+            reply = choice.message.content or ""
+            finish_reason = choice.finish_reason
+            return reply, finish_reason
+        except HfHubHTTPError as exc:
+            logger.exception("HF Hub HTTP error")
+            raise HFClientError(f"فشل الاتصال بنموذج Hugging Face: {exc}") from exc
+        except Exception as exc:  # noqa: BLE001
+            logger.exception("Unexpected error calling HF model")
+            raise HFClientError(f"خطأ غير متوقع أثناء استدعاء النموذج: {exc}") from exc
+
+    async def chat_completion_stream(
+        self,
+        messages: list[ChatMessage],
+        max_new_tokens: int | None = None,
+        temperature: float | None = None,
+        top_p: float | None = None,
+    ) -> AsyncGenerator[str, None]:
+        """يبث الرد تدريجياً (Server-Sent Events) عبر مولّد غير متزامن."""
+        try:
+            stream = await self._client.chat_completion(
+                messages=self._to_hf_messages(messages),
+                max_tokens=max_new_tokens or self._settings.default_max_new_tokens,
+                temperature=(
+                    temperature
+                    if temperature is not None
+                    else self._settings.default_temperature
+                ),
+                top_p=top_p if top_p is not None else self._settings.default_top_p,
+                stream=True,
+            )
+            async for chunk in stream:
+                delta = chunk.choices[0].delta.content
+                if delta:
+                    yield delta
+        except HfHubHTTPError as exc:
+            logger.exception("HF Hub HTTP error during streaming")
+            raise HFClientError(f"فشل الاتصال بنموذج Hugging Face: {exc}") from exc
+        except Exception as exc:  # noqa: BLE001
+            logger.exception("Unexpected error during streaming")
+            raise HFClientError(f"خطأ غير متوقع أثناء البث: {exc}") from exc