Claude API للمطورين — الدليل العربي الشامل من الصفر للإنتاج

pip install anthropic python-dotenv

# ملف .env
ANTHROPIC_API_KEY=sk-ant-api03-your-key-here

import anthropic
from dotenv import load_dotenv
import os

load_dotenv()

client = anthropic.Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

# أول استدعاء
message = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "مرحباً كلود، ما هو الذكاء الاصطناعي؟"}
    ]
)

print(message.content[0].text)

npm install @anthropic-ai/sdk dotenv

import Anthropic from '@anthropic-ai/sdk';
import * as dotenv from 'dotenv';

dotenv.config();

const client = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY
});

async function askClaude(question: string): Promise {
  const message = await client.messages.create({
    model: 'claude-sonnet-4-5',
    max_tokens: 1024,
    messages: [
      { role: 'user', content: question }
    ]
  });

  return (message.content[0] as { type: string; text: string }).text;
}

// تشغيل
askClaude("ما هي أبرز قدرات كلود AI؟").then(console.log);

message = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=2000,
    system="""أنت مساعد قانوني متخصص في القانون التجاري السعودي.
دورك: مساعدة رواد الأعمال في فهم المتطلبات القانونية.

القواعد الصارمة:
- لا تُقدّم استشارة قانونية ملزمة — أنت مساعد معلوماتي فقط
- انصح دائماً بمراجعة محامٍ معتمد للقرارات الحاسمة
- استند للأنظمة السعودية ذات الصلة (نظام الشركات، نظام العمل...)
- اللغة: عربية فصحى سلسة
- الطول: إجابات مفيدة ومباشرة""",
    messages=[
        {"role": "user", "content": "ما متطلبات تأسيس شركة ذات مسؤولية محدودة في السعودية؟"}
    ]
)

# Python Streaming
with client.messages.stream(
    model="claude-sonnet-4-5",
    max_tokens=2000,
    messages=[{"role": "user", "content": "اشرح الذكاء الاصطناعي في 500 كلمة"}]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)  # طباعة حرفاً بحرف
    print()  # سطر جديد في النهاية

// Node.js Streaming مع Express لـ Server-Sent Events
app.get('/stream', async (req, res) => {
  const question = req.query.q as string;

  res.setHeader('Content-Type', 'text/event-stream');
  res.setHeader('Cache-Control', 'no-cache');

  const stream = await client.messages.stream({
    model: 'claude-sonnet-4-5',
    max_tokens: 2000,
    messages: [{ role: 'user', content: question }]
  });

  for await (const chunk of stream) {
    if (chunk.type === 'content_block_delta' &&
        chunk.delta.type === 'text_delta') {
      res.write(`data: ${JSON.stringify({text: chunk.delta.text})}\n\n`);
    }
  }

  res.write('data: [DONE]\n\n');
  res.end();
});

tools = [
    {
        "name": "get_weather",
        "description": "جلب الطقس الحالي لأي مدينة",
        "input_schema": {
            "type": "object",
            "properties": {
                "city": {
                    "type": "string",
                    "description": "اسم المدينة بالعربية أو الإنجليزية"
                },
                "unit": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"],
                    "description": "وحدة الحرارة"
                }
            },
            "required": ["city"]
        }
    },
    {
        "name": "search_database",
        "description": "البحث في قاعدة بيانات المنتجات",
        "input_schema": {
            "type": "object",
            "properties": {
                "query": {"type": "string", "description": "مصطلح البحث"},
                "max_results": {"type": "integer", "description": "عدد النتائج الأقصى"}
            },
            "required": ["query"]
        }
    }
]

# الاستدعاء الأول — كلود يقرر استخدام أداة
response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    tools=tools,
    messages=[{"role": "user", "content": "ما طقس الرياض الآن؟"}]
)

# معالجة طلب الأداة
if response.stop_reason == "tool_use":
    tool_use = next(b for b in response.content if b.type == "tool_use")
    tool_name = tool_use.name
    tool_input = tool_use.input

    # تنفيذ الدالة الفعلية
    if tool_name == "get_weather":
        result = fetch_weather(tool_input["city"])

    # إرسال النتيجة لكلود
    final_response = client.messages.create(
        model="claude-sonnet-4-5",
        max_tokens=1024,
        tools=tools,
        messages=[
            {"role": "user", "content": "ما طقس الرياض الآن؟"},
            {"role": "assistant", "content": response.content},
            {
                "role": "user",
                "content": [{
                    "type": "tool_result",
                    "tool_use_id": tool_use.id,
                    "content": str(result)
                }]
            }
        ]
    )
    print(final_response.content[0].text)

import anthropic

# إنشاء Batch من 1000 طلب
batch_requests = []
for i, text in enumerate(texts_to_classify[:1000]):
    batch_requests.append({
        "custom_id": f"request_{i}",
        "params": {
            "model": "claude-haiku-4-5",
            "max_tokens": 100,
            "messages": [{
                "role": "user",
                "content": f"صنّف هذا النص: {text}\nأجب بكلمة واحدة: إيجابي/سلبي/محايد"
            }]
        }
    })

# إرسال الـ Batch
batch = client.beta.messages.batches.create(requests=batch_requests)
print(f"Batch ID: {batch.id}")

# التحقق من الحالة (قد يستغرق دقائق لساعات)
import time
while True:
    batch_status = client.beta.messages.batches.retrieve(batch.id)
    if batch_status.processing_status == "ended":
        break
    print(f"قيد المعالجة... {batch_status.request_counts}")
    time.sleep(30)

# قراءة النتائج
for result in client.beta.messages.batches.results(batch.id):
    print(f"{result.custom_id}: {result.result.message.content[0].text}")

# لوثيقة طويلة تُستخدم مراراً كسياق
long_document = open("company_manual.txt").read()  # 50,000 كلمة مثلاً

response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "أنت مساعد الشركة. استند لدليل الشركة للإجابة.",
        },
        {
            "type": "text",
            "text": long_document,
            "cache_control": {"type": "ephemeral"}  # تفعيل التخزين المؤقت
        }
    ],
    messages=[{"role": "user", "content": "ما سياسة الإجازات؟"}]
)

# الاستدعاء الثاني يستخدم النسخة المُخزّنة بـ 10% من السعر
print(response.usage)  # cache_read_input_tokens سيكون مرتفعاً

import anthropic
import time
import logging

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

def robust_api_call(prompt: str, max_retries: int = 3) -> str:
    """استدعاء API مع معالجة أخطاء كاملة وإعادة المحاولة"""

    client = anthropic.Anthropic()

    for attempt in range(max_retries):
        try:
            message = client.messages.create(
                model="claude-sonnet-4-5",
                max_tokens=2000,
                messages=[{"role": "user", "content": prompt}]
            )
            return message.content[0].text

        except anthropic.RateLimitError as e:
            # تجاوز حد الطلبات — انتظر وأعد المحاولة
            wait_time = 2 ** attempt  # 1, 2, 4 ثوانٍ
            logger.warning(f"Rate limit. انتظار {wait_time} ثانية...")
            time.sleep(wait_time)

        except anthropic.APIConnectionError as e:
            # مشكلة شبكة
            logger.error(f"خطأ اتصال: {e}")
            if attempt == max_retries - 1:
                raise

        except anthropic.AuthenticationError as e:
            # مفتاح API غير صالح
            logger.error("مفتاح API غير صالح. تحقق من ANTHROPIC_API_KEY")
            raise  # لا فائدة من إعادة المحاولة

        except anthropic.BadRequestError as e:
            # طلب غير صالح (برومبت كبير جداً أو محتوى محظور)
            logger.error(f"طلب غير صالح: {e}")
            raise

        except anthropic.APIError as e:
            # خطأ عام في API
            logger.error(f"خطأ API: {e.status_code} - {e.message}")
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)

    raise Exception("فشلت جميع المحاولات")