# تصمیم با سنجه

> یک متن یا دادهٔ JSON و چند پرسش بسته می‌گیرد و برای هر پرسش جواب و احتمال گزینه‌ها را برمی‌گرداند. سه نوع پرسش دارد: `choice`، `noul` و `score`.

URL: https://dana.expert/docs/api-reference/decide

`POST https://api.dana.expert/v1/decide`

## هدرها

| فیلد | نوع | الزامی | توضیح |
|---|---|---|---|
| `Authorization` | string | بله | کلید API از کنسول دانا: `Authorization: Bearer dn-live-...` |
| `x-api-key` | string | نه | همان کلید، به‌جای هدر `Authorization` |
| `Content-Type` | string | بله | مقدار: `"application/json"` |

## بدنهٔ درخواست

| فیلد | نوع | الزامی | توضیح |
|---|---|---|---|
| `state` | string \| object \| array | بله | متنی که دربارهٔ آن تصمیم گرفته می‌شود: یک رشته، یا هر دادهٔ JSON؛ تا ۲۰٬۰۰۰ کاراکتر |
| `questions` | object | بله | پرسش‌ها: هر کلید نامی است که خودتان می‌گذارید (مثل `dept`) و جواب با همین نام برمی‌گردد؛ ۱ تا ۳۲ کلید |
| `model` | string | نه | `ghanari` (قناری، سریع‌تر) یا `kabootar` (کبوتر، دقیق‌تر)؛ مقدار: `"ghanari"`، `"kabootar"`؛ پیش‌فرض: `"ghanari"` |

**هر کلید در questions نامی است که خودتان می‌گذارید و مقدارش این فیلدها را دارد:**

| فیلد | نوع | الزامی | توضیح |
|---|---|---|---|
| `type` | string | بله | نوع پرسش: `choice` یک گزینه از چند گزینه، `noul` بله یا خیر، `score` یک پله روی طیفی مرتب؛ مقدار: `"choice"`، `"noul"`، `"score"` |
| `instructions` | string | بله | متن پرسش؛ کوتاه و روشن، مثل «مربوط به کدام بخش است؟» |
| `criteria` | string[] \| object | نه | برای `choice` فهرست گزینه‌ها، یا شیئی از گزینه به توضیح آن؛ برای `score` پله‌ها از کم به زیاد؛ برای `noul` لازم نیست |

نمونه:

```json
{
  "state": "سه روز است سفارشم را پرداخت کرده‌ام ولی هنوز ارسال نشده.",
  "questions": {
    "dept": {
      "type": "choice",
      "instructions": "مربوط به کدام بخش است؟",
      "criteria": [
        "مالی",
        "فنی",
        "ارسال کالا"
      ]
    },
    "complaint": {
      "type": "noul",
      "instructions": "آیا این پیام شکایت است؟"
    },
    "anger": {
      "type": "score",
      "instructions": "نویسنده چقدر عصبانی است؟",
      "criteria": [
        "آرام",
        "کمی ناراحت",
        "عصبانی"
      ]
    }
  }
}
```

## پاسخ `200`

جواب هر پرسش

| فیلد | نوع | الزامی | توضیح |
|---|---|---|---|
| `model` | string | بله | مدلی که جواب داد: `ghanari` یا `kabootar` |
| `model_version` | string | نه | نسخهٔ همان مدل، مثل `ghanari-ir-v0.1` |
| `answers` | object | بله | جواب هر پرسش، با همان کلیدی که در `questions` فرستادید |
| `usage` | object | نه | توکن‌هایی که خود مدل خواند؛ هزینه با شمارش gateway حساب می‌شود |
| `latency_ms` | number | نه | زمان پاسخ مدل به میلی‌ثانیه |

**هر کلید در answers نامی است که خودتان می‌گذارید و مقدارش این فیلدها را دارد:**

| فیلد | نوع | الزامی | توضیح |
|---|---|---|---|
| `type` | string | بله | مقدار: `"choice"`، `"noul"`، `"score"` |
| `choice` | string | نه | برای `choice`: گزینهٔ برنده |
| `noul` | number | نه | برای `noul`: احتمال «بله»؛ ۰ تا ۱ |
| `score` | number | نه | برای `score`: عددی از ۰ تا شمارهٔ آخرین پله |
| `legend` | object | نه | برای `score`: نام هر پله |
| `probabilities` | object | نه | احتمال هر گزینه یا پله |
| `confidence` | number | بله | اطمینان مدل به جوابش؛ تضمین درستی نیست؛ ۰ تا ۱ |

**فیلدهای usage:**

| فیلد | نوع | الزامی | توضیح |
|---|---|---|---|
| `input_tokens` | integer | نه |  |
| `output_tokens` | integer | نه |  |

نمونه:

```json
{
  "model": "ghanari",
  "model_version": "ghanari-ir-v0.1",
  "answers": {
    "dept": {
      "type": "choice",
      "choice": "ارسال کالا",
      "probabilities": {
        "مالی": 0.0181,
        "فنی": 0.0203,
        "ارسال کالا": 0.9616
      },
      "confidence": 0.8278
    },
    "complaint": {
      "type": "noul",
      "noul": 0.9521,
      "confidence": 0.9521
    },
    "anger": {
      "type": "score",
      "score": 1.7202,
      "legend": {
        "0": "آرام",
        "1": "کمی ناراحت",
        "2": "عصبانی"
      },
      "probabilities": {
        "0": 0.0283,
        "1": 0.2232,
        "2": 0.7485
      },
      "confidence": 0.406
    }
  },
  "usage": {
    "input_tokens": 218,
    "output_tokens": 0
  },
  "latency_ms": 78.2
}
```

## خطاها

| کد | یعنی |
|---|---|
| `400` | بدنهٔ درخواست درست نیست؛ پیام می‌گوید کدام فیلد |
| `401` | کلید نرسید یا شناخته نشد |
| `429` | سقف درخواست، ظرفیت یا اعتبار؛ `type` و `code` علت را می‌گویند |
| `503` | مدل همین حالا در دسترس نیست (`model_unavailable`)؛ چند دقیقه بعد دوباره بفرستید |

فرمت خطا:

```json
{
  "error": {
    "message": "Request body must include 'text' as a string.",
    "type": "invalid_request_error",
    "param": null,
    "code": null
  }
}
```