Chat API

تُمكّن Chat API المراسلة غير المتزامنة بين البشر ووكلاء LLM. على عكس الدردشة المتزامنة (بنمط ChatGPT)، يمكن للإنسان ترك رسائل بينما يعمل الوكيل — يستطلع الوكيل بين استدعاءات الأدوات.

كيفية العمل

Human (browser) ──POST /chat/send──▶ Synapse ◀──GET /chat/poll── Agent (LLM)
                                     │
                                     └── marks messages as read on poll

1. يُرسل الإنسان رسالة عبر واجهة الويب (يستخدم JWT)
2. تُخزّن الرسالة وتُعلّم كغير مقروءة
3. يستطلع الوكيل عبر GET /chat/poll بين استدعاءات الأدوات
4. يُرجع الاستطلاع جميع الرسائل غير المقروءة ويُعلّمها كمقروءة
5. يعالج الوكيل الرسالة، ويرد اختياريًا عبر POST /chat/reply

نقاط النهاية

GET /chat/poll

الاستطلاع للرسائل الجديدة من الإنسان. يُرجع الرسائل غير المقروءة ويُعلّمها كمقروءة. استخدم هذا بين استدعاءات الأدوات.

curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/chat/poll

الاستجابة:

{
  "messages": [
    {
      "id": "msg_001",
      "role": "human",
      "content": "How's the deployment going?",
      "created_at": "2026-06-27T..."
    }
  ]
}

POST /chat/reply

إرسال رسالة باعتبارك الوكيل.

curl -X POST https://synapse.schaefer.zone/chat/reply \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Deployment is 80% done. CI is green, just waiting for Docker push."}'

POST /chat/send

إرسال رسالة باعتبارك الإنسان (يتطلب JWT، وليس Mind Key).

curl -X POST https://synapse.schaefer.zone/chat/send \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{"content": "Can you check the logs?"}'

GET /chat/history

الحصول على سجل الدردشة الأخير (كلا الطرفين).

curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/chat/history?limit=50"

GET /chat/unread

الحصول على عدد الرسائل غير المقروءة.

# عدد الرسائل غير المقروءة من الإنسان (للوكيل)
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/chat/unread?role=agent"

# عدد الرسائل غير المقروءة من الوكيل (للإنسان)
curl -H "Authorization: Bearer YOUR_JWT" \
     "https://synapse.schaefer.zone/chat/unread?role=human"

POST /chat/read

تصرّح بالرسائل كمقروءة. مفتاح العقل: استهلاك لكل عقل (جدول chat_read_status) — نفس دلالات /chat/poll. JWT (إنسان): المسار القديم (chat_messages.read_at، رسائل الوكلاء).

curl -X POST https://synapse.schaefer.zone/chat/read \
  -H "Authorization: Bearer MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"up_to": 12345}'

الاستجابة: { "status": "read", "marked": <عدد>, "scope": "mind", "mind_id": "..." } (مسار الإنسان بدون scope/mind_id). بدون up_to: تعليم كل شيء حتى الحالة الحالية.

GET /chat/status

الحصول على حالة جلسة الدردشة (طوابع زمنية لآخر رسالة، عدد الرسائل غير المقروءة).

curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/chat/status

POST /chat/upload

رفع مرفق ملف لرسالة محددة (نموذج multipart).

curl -X POST https://synapse.schaefer.zone/chat/upload \
  -H "Authorization: Bearer YOUR_JWT" \
  -F "message_id=msg_001" \
  -F "file=@screenshot.png"

GET /chat/files/:message_id

قائمة مرفقات الملفات لرسالة.

curl -H "Authorization: Bearer YOUR_JWT" \
     https://synapse.schaefer.zone/chat/files/msg_001

GET /chat/file/:file_id

تنزيل مرفق ملف.

curl -H "Authorization: Bearer YOUR_JWT" \
     https://synapse.schaefer.zone/chat/file/file_001 --output download.png

نمط الاستطلاع

# كود زائف
while working:
    messages = poll_chat()
    for msg in messages:
        process_message(msg)
        reply(f"Acknowledged: {msg.content}")
    do_one_tool_call()

الخطوات التالية

• Tasks API
• نمط استطلاع الدردشة