# الأدوات المساعدة

نقاط النهاية `/tools` أدوات عامة — لا تتطلب مصادقة.
مفيدة لوكلاء LLM الذين يحتاجون وقتًا من جانب الخادم، أو حسابات آمنة، أو قيمًا
عشوائية.

## GET /tools/time

الحصول على وقت الخادم الحالي، والمنطقة الزمنية، وإزاحة UTC.

```bash
curl https://synapse.schaefer.zone/tools/time
```

الاستجابة:

```json
{
  "time": "2026-06-27T14:30:00.000Z",
  "timezone": "Europe/Berlin",
  "offset": 120
}
```

حالة الاستخدام: وكلاء LLM الذين يحتاجون معرفة "كم الساعة الآن" للجدولة،
أو الطوابع الزمنية، أو حسابات التاريخ النسبية.

## GET /tools/calc

حاسبة آمنة — حسابات حسابية فقط، دون `eval()`. تدعم `+`، `-`، `*`، `/`،
`%`، `(`، `)`، والأرقام.

```bash
curl "https://synapse.schaefer.zone/tools/calc?expr=(10+5)*3"
```

الاستجابة:

```json
{
  "result": 45,
  "expr": "(10+5)*3"
}
```

> [!TIP]
> استخدم هذا بدلاً من محاولة إجراء الحسابات ذهنيًا أو عبر تحليل السلاسل.
> إنه آمن (لا يُمكن حقن كود) ودقيق.

### المعاملات المدعومة

- `+` جمع
- `-` طرح
- `*` ضرب
- `/` قسمة
- `%` باقي القسمة
- `(` `)` أقواس
- أرقام (صحيحة وعشرية)

### أمثلة

```bash
curl ".../tools/calc?expr=2+2"          # → 4
curl ".../tools/calc?expr=3.14*100"     # → 314
curl ".../tools/calc?expr=100%7"        # → 2
curl ".../tools/calc?expr=(2+3)*4-1"    # → 19
```

## GET /tools/random

توليد قيم عشوائية.

```bash
# UUID v4
curl "https://synapse.schaefer.zone/tools/random?type=uuid"
# → { "value": "a1b2c3d4-...", "type": "uuid" }

# عدد صحيح (النطاق الافتراضي 0-100)
curl "https://synapse.schaefer.zone/tools/random?type=int&min=1&max=10"
# → { "value": 7, "type": "int" }

# عدد عشري
curl "https://synapse.schaefer.zone/tools/random?type=float&min=0&max=1"
# → { "value": 0.7234, "type": "float" }

# سلسلة hex
curl "https://synapse.schaefer.zone/tools/random?type=hex&min=8&max=16"
# → { "value": "a3f7b2c1", "type": "hex" }

# سلسلة أبجدية
curl "https://synapse.schaefer.zone/tools/random?type=alpha&min=8&max=12"
# → { "value": "kQmzPwXn", "type": "alpha" }
```

### معاملات النوع

| النوع | المعاملات | المخرجات |
|------|-----------|--------|
| `uuid` | لا شيء | سلسلة UUID v4 |
| `int` | `min`، `max` (افتراضي 0-100) | عدد صحيح |
| `float` | `min`، `max` (افتراضي 0-100) | عدد عشري |
| `hex` | `min`، `max` (نطاق الطول، افتراضي 8-16) | سلسلة hex |
| `alpha` | `min`، `max` (نطاق الطول، افتراضي 8-16) | سلسلة أبجدية |

## حالات الاستخدام لوكلاء LLM

### توليد معرّفات فريدة

```bash
ID=$(curl -s .../tools/random?type=uuid | jq -r .value)
curl -X POST .../memory -d "{\"key\": \"task_$ID\", ...}"
```

### حساب النسب المئوية

```bash
TOTAL=142
DONE=87
PERCENT=$(curl -s ".../tools/calc?expr=($DONE*100)/$TOTAL" | jq -r .result)
echo "Progress: $PERCENT%"
```

### الحصول على الطابع الزمني الحالي

```bash
NOW=$(curl -s .../tools/time | jq -r .time)
curl -X POST .../var -d "{\"key\": \"last_run\", \"value\": \"$NOW\"}"
```

### توليد بيانات اختبار

```bash
for i in {1..10}; do
  NAME=$(curl -s ".../tools/random?type=alpha&min=5&max=10" | jq -r .value)
  curl -X POST .../memory -d "{\"key\": \"test_$i\", \"content\": \"$NAME\"}"
done
```

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

- [نظرة عامة على الـ API](/docs/api/overview) — جميع مجموعات نقاط النهاية
- [الأخطاء ومعالجتها](/docs/api/errors)