الصوت والوسائط

تستطيع كاظمة السماع (تحويل الكلام إلى نص)، والتحدث (تحويل النص إلى كلام)، والرؤية (صور/PDF/مستندات) عبر كل منصات الدردشة — Telegram وDiscord وSlack وواجهة الويب.

---

الصوت (STT + TTS)

الصوت كتلة إعداد واحدة تتحكم بكل المنصات. عند التفعيل يُنسخ الصوت الوارد إلى نص قبل وصوله للوكيل. ردود الملاحظات الصوتية التلقائية (tts_reply) تولّد صوتًا فقط عندما كان الدور الوارد صوتيًا (وليس لنص عادي).

تفعيل الصوت

في kazma.yaml تحت gateway، أو وقت التشغيل عبر الويب → الإعدادات → الصوت:

gateway:
  voice:
    enabled: true
    tts_reply: true
    stt_provider: openai
    stt_language: auto
    tts_provider: edgetts
    tts_voice: default
    tts_output_format: mp3

الإعداد	الأثر
نظام الصوت (enabled)	تشغيل/إيقاف رئيسي لـ STT + TTS
ردود صوتية تلقائية (tts_reply)	بعد وارد صوتي فقط؛ إيقاف = ردود نصية مع بقاء STT

نفس المفاتيح تُقرأ حيًا من كل المُكيّفات (voice_helpers.py).

مزوّدو STT

المزوّد	المفتاح	يحتاج	ملاحظات
OpenAI Whisper	openai	OPENAI_API_KEY	الافتراضي
Groq Whisper	groq	GROQ_API_KEY	الأسرع
Cohere	cohere	COHERE_API_KEY
NVIDIA NIM / Riva	nvidia	NVIDIA_API_KEY
faster-whisper (محلي)	faster-whisper	pip install faster-whisper	بلا مفتاح API

مزوّدو TTS

المزوّد	المفتاح	يحتاج	ملاحظات
Edge TTS	edgetts	لا شيء	مجاني — الافتراضي
OpenAI	openai	OPENAI_API_KEY	أصوات عصبية عالية الجودة
NVIDIA NIM	nvidia	NVIDIA_API_KEY
Kokoro (محلي)	kokoro	تثبيت محلي
Coqui (محلي)	coqui	تثبيت محلي

السلوك لكل منصة

المنصة	وارد (أنت → الوكيل)	صادر (الوكيل → أنت)
Telegram	ملاحظة صوتية → نص	رد صوتي فقط إن tts_reply وكان الدور صوتيًا
Discord	مرفق صوتي → نص	نفس الشرط؛ رفع ملف
Slack	ملف صوتي → نص	نفس الشرط
Web UI	POST /api/voice/stt	POST /api/voice/tts / /ws/voice (لا يُقيَّد بـ tts_reply المنصة)

إن لم يُضبط STT، ملاحظة صوتية واردة تعيد رسالة احتياطية ودّية بدل الفشل الصامت.

---

الوسائط والمرفقات

عقد الرسالة يحمل قائمة attachments (Attachment في gateway.py) إلى جانب النص. كل مرفق له kind (image / file / audio / video)، mime، filename، وإما data في الذاكرة أو url قابل للجلب.

كيف يستلم الوكيل الوسائط

نوع المرفق	السلوك
صورة (PNG/JPEG/WEBP/GIF، ≤ 8 MB)	تُضمَّن ككتلة vision base64 — يرى النموذج الصورة مباشرة
مستند (PDF/DOCX/صورة كبيرة/صوت/…)	يُحفظ في kazma-data/attachments/؛ الموجّه يحصل على [Attached: foo.pdf — use file_read…]

صيغة الرؤية OpenAI (content: [{type:image_url,...}, {type:text,...}]) تمر عبر llm_provider.py كما هي — أي نموذج يدعم الرؤية يعمل.

الدعم لكل منصة

المنصة	وارد	صادر
Telegram	صورة / مستند / فيديو / رسوم	sendPhoto / sendDocument / …
Discord	مرفقات + embeds صور	رفع multipart
Slack	files (Socket Mode)	مسار رفع Slack الخارجي
Web UI	POST /api/chat/upload (حد 20 MB)	روابط تنزيل

إرسال وسائط من واجهة الويب

1. زر المرفق (📎) في صندوق الدردشة.
2. ملفات نصية صغيرة (≤ 1 MB) تُضمَّن من جهة العميل.
3. صور وPDF وثنائي تُرفع عبر POST /api/chat/upload.

الوكيل يمكنه أيضًا إنتاج وسائط — مثل generate_image → kazma-data/images/.

---

التعطيل

الصوت والوسائط اختيارية. الصوت افتراضيًا enabled: false. التقاط الوسائط يعمل حيث يدعمه المُكيّف؛ كبح الصادر يكون لكل أداة (الوكيل يرسل فقط ما ينشئه صراحة).