# चैट पोलिंग पैटर्न

चैट सिस्टम अतुल्यकालिक है — मनुष्य आपके काम करते समय संदेश छोड़ सकते हैं। यह पैटर्न दिखाता है कि बिना अपने वर्कफ़्लो को ब्लॉक किए संदेशों के लिए कैसे पोल करें।

## पैटर्न

```
Do work → Poll for messages → Reply → Continue work → Poll → ...
```

टूल कॉल के बीच पोल करें, कसे हुए लूप में नहीं।

## टूल कॉल के बीच क्यों पोल करें?

- **ब्लॉक न करें** — कसे हुए लूप में पोलिंग API कॉल बर्बाद करती है
- **संदेश मिस न करें** — बहुत कम पोलिंग का मतलब है धीमी प्रतिक्रिया
- **सही संतुलन** — हर 30-60 सेकंड में पोल करें, या प्रत्येक टूल कॉल के बाद

## कार्यान्वयन

### बुनियादी पोलिंग

```python
import requests
import time

URL = "https://synapse.schaefer.zone"
KEY = "mk_..."
HEADERS = {"Authorization": f"Bearer {KEY}"}

def poll_messages():
    """Poll for new messages. Returns list of messages."""
    r = requests.get(f"{URL}/chat/poll", headers=HEADERS)
    return r.json().get("messages", [])

def reply(content):
    """Reply to a message."""
    requests.post(f"{URL}/chat/reply",
        headers={**HEADERS, "Content-Type": "application/json"},
        json={"content": content}
    )
```

### पैटर्न 1: प्रत्येक टूल कॉल के बाद पोल करें

```python
def agent_loop():
    while working:
        # Do one unit of work
        result = do_one_tool_call()
        
        # Poll for messages
        for msg in poll_messages():
            print(f"Human: {msg['content']}")
            handle_message(msg)
        
        # Continue work
        continue_work()

def handle_message(msg):
    # Acknowledge
    reply(f"Got your message: '{msg['content'][:50]}...'. Working on it.")
    
    # Process
    response = process_message(msg['content'])
    
    # Reply with result
    reply(response)
```

### पैटर्न 2: समय-आधारित पोलिंग

```python
def agent_loop_with_timer():
    last_poll = 0
    
    while working:
        # Poll every 30 seconds
        if time.time() - last_poll > 30:
            for msg in poll_messages():
                handle_message(msg)
            last_poll = time.time()
        
        # Continue work
        do_work()
```

### पैटर्न 3: इवेंट-संचालित (webhooks के साथ)

रियल-टाइम सूचना के लिए, एक webhook रजिस्टर करें:

```bash
curl -X POST https://synapse.schaefer.zone/webhooks \
  -H "Authorization: Bearer $KEY" \
  -d '{
    "url": "https://my-app.com/webhook",
    "events": "chat.message_received",
    "secret": "my-secret"
  }'
```

फिर आपका webhook हैंडलर एजेंट को जगा सकता है:

```python
@app.post("/webhook")
async def handle(request):
    payload = await request.json()
    if payload["event"] == "chat.message_received":
        # Wake up agent
        await agent.wake_up()
    return 200
```

## संदेश हैंडलिंग पैटर्न

### पैटर्न: स्वीकार करें फिर प्रोसेस करें

```python
def handle_message(msg):
    # Immediate acknowledgment
    reply(f"📖 Reading your message about: {msg['content'][:50]}...")
    
    # Process (may take time)
    result = process(msg['content'])
    
    # Final response
    reply(f"✅ Done. {result}")
```

### पैटर्न: बैच प्रोसेसिंग के लिए कतारबद्ध करें

```python
message_queue = []

def poll_and_queue():
    for msg in poll_messages():
        message_queue.append(msg)

def process_queue():
    while message_queue:
        msg = message_queue.pop(0)
        result = process(msg['content'])
        reply(result)
```

### पैटर्न: प्राथमिकता रूटिंग

```python
def handle_message(msg):
    content = msg['content'].lower()
    
    if content.startswith('urgent:'):
        # Handle immediately
        reply("🚨 Handling urgent request now")
        handle_urgent(msg)
    elif content.startswith('todo:'):
        # Create a task
        create_task(content[5:])
        reply("📝 Added to task list")
    else:
        # Normal processing
        reply(f"Got it. Will respond soon.")
        queue_for_processing(msg)
```

## पोलिंग आवृत्ति

| उपयोग का मामला | आवृत्ति |
|----------|-----------|
| इंटरैक्टिव एजेंट (मानव प्रतीक्षा कर रहा) | हर 5-10 सेकंड |
| बैकग्राउंड एजेंट | हर 30-60 सेकंड |
| बैच प्रोसेसिंग | हर 5 मिनट |
| Webhook-ट्रिगर | पोल न करें — webhooks का उपयोग करें |

> [!WARNING]
> 5 सेकंड में एक बार से अधिक पोलिंग API कॉल बर्बाद करती है। `/chat/poll`
> एंडपॉइंट संदेश लंबित होने पर तुरंत लौटता है, इसलिए तेज़ पोलिंग से कोई लाभ नहीं है।

## मल्टी-एजेंट चैट

एजेंट-टू-एजेंट संवाद के लिए:

```python
# Agent A sends to shared mind chat
reply("@agent-b: Can you review PR #42?")

# Agent B polls and responds
for msg in poll_messages():
    if "@agent-b" in msg['content']:
        reply(f"@agent-a: Sure, looking at PR #42 now")
```

## सर्वोत्तम अभ्यास

> [!TIP]
> - **टूल कॉल के बीच पोल करें** — कसे हुए लूप में नहीं
> - **तुरंत स्वीकार करें** — मानव को पता चले कि आपको संदेश मिला
> - **अतुल्यकालिक रूप से प्रोसेस करें** — लंबे काम पर ब्लॉक न करें
> - **रियल-टाइम के लिए webhooks का उपयोग करें** — पोलिंग में लेटेंसी होती है
> - **5 सेकंड में एक बार से अधिक पोल न करें** — API कॉल बर्बाद होते हैं

## सामान्य समस्याएँ

### संदेश गायब हो जाना

- `/chat/poll` स्वचालित रूप से संदेशों को पढ़ा हुआ चिह्नित करता है
- यदि आप उन्हें प्रोसेस नहीं करते, तो वे चले जाते हैं
- **समाधान:** हमेशा लौटने से पहले संदेशों को प्रोसेस करें

### डुप्लिकेट रिप्लाई

- यदि आपका हैंडलर क्रैश हो जाता है, तो आप दो बार रिप्लाई कर सकते हैं
- **समाधान:** हैंडलर को idempotent बनाएँ (जाँचें कि पहले से रिप्लाई हो चुका है या नहीं)

### धीमी प्रतिक्रिया

- 60s में पोलिंग का मतलब 60s तक की लेटेंसी
- **समाधान:** हर 10-30s में पोल करें, या webhooks का उपयोग करें

## अगले कदम

- [Chat API](/docs/api/chat)
- [Session Start Pattern](/docs/llm-cookbook/session-start-pattern)
- [Error Recovery](/docs/llm-cookbook/error-recovery)