> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gorbit.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# المفاهيم الأساسية

> المفاهيم والمصطلحات الأساسية للعمل مع Gorbit APIs

## الإجراءات و MCP

<AccordionGroup>
  <Accordion title="الإجراءات" icon="wrench">
    الإجراءات (تسمى أيضاً الأدوات في الواجهة الخلفية)
    هي الوظائف التي يمكن لعمالك تنفيذها للتفاعل مع الأنظمة والخدمات الخارجية.
    إنها توسع قدرات وكلائك إلى ما بعد نموذج اللغة فقط.

    الإجراءات المدمجة:

    | Name             | Description                                                             | Requires Config | Provider Choices                          |
    | ---------------- | ----------------------------------------------------------------------- | --------------- | ----------------------------------------- |
    | Internal Search  | Search through your organization's indexed documents and knowledge base | Yes             | Built-in with swappable components        |
    | Web Search       | Search the internet for real-time information and current events        | Yes             | Google, Serper, Exa, Firecrawl (optional) |
    | Code Interpreter | Execute Python code, analyze data, and generate visualizations          | No              | Built-in                                  |
    | Image Generation | Create images from text descriptions using AI models                    | Yes             | OpenAI, Azure OpenAI                      |

    <Info>
      دعم SCIM لموفري الهوية الشائع قريباً!
    </Info>

    الإجراءات المخصصة:

    * **تكاملات API**: الاتصال بـ REST APIs الخارجية
    * **عمليات قواعد البيانات**: الاستعلام وتحديث قواعد البيانات
    * **أتمتة سير العمل**: تشغيل عمليات الأعمال
    * **عمليات الملفات**: القراءة والكتابة ومعالجة الملفات

    يمكنك تعريف الإجراءات المخصصة الخاصة بك في لوحة الإدارة باستخدام مواصفات OpenAPI.
  </Accordion>

  <Accordion title="MCP" icon="handshake">
    بروتوكول سياق النموذج (MCP)
    هو معيار مفتوح يتيح لمساعدي الذكاء الاصطناعي الوصول بأمان إلى مصادر البيانات والأدوات الخارجية.
    يمكن تهيئة Gorbit كعميل MCP للتفاعل مع الأنظمة وقواعد البيانات،
    و APIs بطريقة محكومة.

    الميزات الرئيسية لـ MCP:

    * **الوصول للبيانات الخارجية**: الاتصال بقواعد البيانات و APIs وأنظمة الملفات
    * **المصادقة**: التمرير عبر OAuth لضمان الوصول الآمن لخادم MCP الخاص بك.
  </Accordion>

  <Accordion title="(متقدم) الإجراءات المدمجة المخصصة" icon="wrench">
    في بعض الأحيان، تحتاج إلى مزيد من التحكم في إجرك أكثر مما هو ممكن مع الإجراء المخصص.
    بما أن Gorbit مفتوح المصدر، يمكنك توسيع الإجراءات المدمجة حسب رغبتك!

    للعثور على قوالب الإجراءات المدمجة،
    راجع `backend/gorbit/tools/tool_implementations` في [مستودع Gorbit](https://github.com/gorbit-dot-app/gorbit).

    <Warning>
      توسيع قاعدة الكود غير موصى به لمعظم المستخدمين. قبل أن تبدأ،
      يرجى التواصل معنا على
      [Slack](https://join.slack.com/t/gorbit-dot-app/shared_invite/zt-34lu4m7xg-TsKGO6h8PDvR5W27zTdyhA)
      أو [Discord](https://discord.gg/TDJ59cGV2X) للحصول على الدعم!
    </Warning>
  </Accordion>
</AccordionGroup>

## الوكلاء

<AccordionGroup>
  <Accordion title="الوكلاء" icon="user">
    الوكلاء هم مساعدي ذكاء اصطناعي مع تعليمات وإجراءات ووصول للبيانات مخصصة توسع قدرات LLM الأساسية.

    <Note>
      The terms *Personas*, *Assistants*,
      and *Agents* are used interchangeably throughout Gorbit and refer to the same concept.
    </Note>

    **الوكلاء المدمجون:**

    * `id: 0` وكيل البحث - يستخدم أداة البحث للإجابة على الأسئلة من قاعدة المعرفة الخاصة بك
    * `id: -1` الوكيل العام - محادثة أساسية بدون أدوات (محادثة أساسية مع LLM)
    * `id: -2` وكيل إعادة الصياغة - يستخدم أداة البحث ويقتبس مقتطفات دقيقة من المصادر
    * `id: -3` وكيل الفن - ينشئ صوراً ومحتوى مرئياً

    يمكنك إنشاء وكلائك الخاصين في لوحة الإدارة أو عبر API.

    **معظم نقاط نهاية المحادثة تتطلب معرف الوكيل**

    للعثور على معرف الوكيل الخاص بك، يمكنك:

    * استخدام نقطة نهاية API `GET /persona` لعرض قائمة جميع الوكلاء
    * في لوحة الإدارة: انقر على وكيل وتحقق من الرقم الأول في URL
  </Accordion>
</AccordionGroup>

## المحادثة

<AccordionGroup>
  <Accordion title="استجابات المحادثة المبثوقة" icon="comment">
    يستخدم نظام استجابة المحادثة بنية قائمة على الحزم لتقديم استجابات في الوقت الفعلي للمستخدمين.
    بدلاً من انتظار استجابة كاملة،
    يقوم النظام بتقسيم تفاعل المحادثة إلى حزم منفصلة يمكن بثها بشكل تدريجي.

    كل حزمة تتبع بنية متسقة محددة بواسطة فئة `Packet`:

    ```python theme={null}
    class Packet(BaseModel):
      ind: int        # فهرس تسلسلي للترتيب
      obj: PacketObj  # المحتوى الفعلي بما في ذلك نوع الحزمة
    ```

    **تدفق البث:**

    * يطلب طلب المحادثة تشغيل عملية البث
    * يتم إنشاء أنواع مختلفة من الحزم بناءً على العمليات المطلوبة
      (التفكير، استدعاءات الأدوات، استجابة AI، المستندات، الاستشهادات، إلخ)
    * يتم إرسال الحزم بفهارس تسلسلية للحفاظ على الترتيب
    * تعالج الواجهة الأمامية الحزم في الوقت الفعلي لتحديث واجهة المستخدم
    * حزمة `OverallStop` تشير إلى الاكتمال
  </Accordion>

  <Accordion title="حزم الرسائل الأساسية" icon="message">
    **MessageStart و MessageDelta**

    تشكل هذه الحزم جوهر نظام الاستجابة المبثوقة:

    * **MessageStart**: تبدأ رسالة جديدة بمحتوى أولي ومستندات البحث النهائية (إن وجدت)
    * **MessageDelta**: تقدم محتوى نصي تزايدي أثناء إنشائه
  </Accordion>

  <Accordion title="حزم التحكم" icon="gear">
    **إدارة الجلسة والقسم**

    تدير حزم التحكم تدفق ودورة حياة عملية البث:

    * **OverallStop**: تشير إلى نهاية جلسة البث بالكامل
    * **SectionEnd**: تحدد اكتمال نوع حزمة (التفكير، الرسالة، الاستشهادات، إلخ)
  </Accordion>

  <Accordion title="حزم الأدوات" icon="wrench">
    يتم بث استجابات الأدوات بنفس طريقة استجابة الرسالة الرئيسية.

    **أدوات البحث**

    * SearchToolStart و SearchToolDelta تتعامل مع عمليات البحث في المستندات

    **توليد الصور**

    * ImageGenerationToolStart و ImageGenerationToolDelta و ImageGenerationToolHeartbeat تدير إنشاء صور AI

    **الأدوات المخصصة**

    * CustomToolStart و CustomToolDelta تُستخدم لـ MCP والإجراءات المخصصة

    حزمة البداية تشير إلى بدء استجابة الأداة.
    حزم الدلتا تبث النتائج كما تصبح متاحة.
  </Accordion>

  <Accordion title="حزم التفكير" icon="lightbulb">
    يتم بث أي خطوات تفكير لتتمكن الواجهة الأمامية من عرضها أثناء معالجة النظام.
    حزم التفكير عادةً هي الأولى التي يتم إرسالها.

    * **ReasoningStart**: تبدأ قسم التفكير
    * **ReasoningDelta**: تبث عملية تفكير AI
  </Accordion>

  <Accordion title="حزم الاستشهاد" icon="quote-right">
    تربط حزم الاستشهاد معرفات الاستشهاد بمعرفات المستندات.

    * **CitationStart**: تبدأ نتائج الاستشهاد
    * **CitationDelta**: تقدم استشهادات ومراجع المصادر
  </Accordion>
</AccordionGroup>

## الموصلات

<Tip>
  عندما ترى مصطلح *Connector* في Gorbit أو في مكان آخر من هذا التوثيق،
  نشير عموماً إلى *ConnectorCredentialPairs*
</Tip>

<AccordionGroup>
  <Accordion title="الموصلات" icon="plug">
    `Connectors` في Gorbit تحدد البيانات التي تريد فهرستها

    * `name`: لا يُعرض فعلياً في الواجهة إذا تم تعيين `ConnectorCredentialPairMetadata:name`
    * `source`: النظام الذي سيتم الاتصال به (راجع قسم `DocumentSource` أدناه)
    * `input_type`: كيف يسترجع `Connector` البيانات (راجع قسم `InputType` أدناه)
    * `connector_specific_config`: إعدادات خاصة بالمصدر مثل مسارات المجلدات أو القنوات. ستحتاج إلى مراجعة [`/backend/gorbit/connectors`](https://github.com/gorbit-dot-app/gorbit/tree/main/backend/gorbit/connectors) للتكوينات الخاصة بكل موصل.
    * `refresh_freq`: مدى التكرار للتحقق من المحتوى الجديد أو المحدث بالثواني
    * `prune_freq`: مدى التكرار لإزالة المحتوى القديم من Gorbit بالثواني
    * `indexing_start`: تاريخ ووقت اختياري لتحديد متى يجب أن تبدأ الفهرسة

    ```python Python theme={null}
    class ConnectorBase(BaseModel):
      name: str
      source: DocumentSource
      input_type: InputType
      connector_specific_config: dict[str, Any]
      refresh_freq: int | None = None
      prune_freq: int | None = None
      indexing_start: datetime | None = None
    ```
  </Accordion>

  <Accordion title="بيانات الاعتماد" icon="key">
    تحتوي `Credentials` على تفاصيل المصادقة اللازمة للوصول إلى مصادر البيانات. تشمل مفاتيح API،
    رموز OAuth، رموز الوصول الشخصية (PATs)،
    أو بيانات اعتماد حساب الخدمة التي تسمح لـ Gorbit بالاتصال بأمان بأنظمتك الخارجية.

    أنواع `Credentials`:

    * **مفاتيح API**: مصادقة بسيطة قائمة على الرمز
    * **رموز OAuth**: تفويض مفوض مع إمكانيات التحديث
    * **حسابات الخدمة**: مصادقة آلة إلى آلة
    * **رموز الوصول الشخصية**: بيانات اعتماد وصول خاصة بالمستخدم
  </Accordion>

  <Accordion title="ConnectorCredentialPairs" icon="link">
    خلف الكواليس، يتم دمج `Connectors` و `Credentials` في `ConnectorCredentialPair` (CC-pair).
    CC-pair هو اتصال نشط يمكنه مزامنة البيانات من مصادرك الخارجية إلى Gorbit.
    CC-pairs هي ما تراه وتديره في صفحة `Connectors` في الإدارة.

    وظائف CC-pair:

    * **الاتصالات النشطة**: مزامنة البيانات المباشرة بين المصدر و Gorbit
    * **مراقبة الحالة**: تتبع صحة المزامنة والأداء
    * **التحكم في الوصول**: إدارة من يمكنه رؤية البيانات من هذا الاتصال
    * **إدارة التكوين**: تحديث إعدادات المزامنة وبيانات الاعتماد

    <Warning>
      إذا كنت تنشئ `Connectors` من خلال API، يجب ربطها بـ `Credential` (CC-pair)
      لجعلها نشطة!
    </Warning>
  </Accordion>

  <Accordion title="ConnectorCredentialPairMetadata" icon="gear">
    يحدد `ConnectorCredentialPairMetadata` التكوين وإعدادات الوصول لـ CC-pair.

    خيارات التكوين:

    * `name`: اسم عرض اختياري لـ CC-pair (يتجاوز اسم `Connector`)
    * `access_type`: من يمكنه الوصول إلى البيانات من هذا CC-pair (راجع قسم `AccessType` أدناه)
    * `auto_sync_options`: تكوين اختياري لإعدادات المزامنة التلقائية
    * `groups`: قائمة معرفات المجموعات التي لديها حق الوصول إلى هذا CC-pair

    ```python Python theme={null}
    class ConnectorCredentialPairMetadata(BaseModel):
      name: str | None = None
      access_type: AccessType
      auto_sync_options: dict[str, Any] | None = None
      groups: list[int] = Field(default_factory=list)
    ```
  </Accordion>
</AccordionGroup>

## المستندات

<AccordionGroup>
  <Accordion title="DocumentBase" icon="page">
    `DocumentBase` هي بنية أساسية تُستخدم في جميع أنحاء Gorbit لتخزين وإدارة بيانات المستندات.
    لاحظ أن التضمينات مخزنة في Vespa بشكل منفصل.

    * `id`: معرف فريد. يتم إنشاؤه بواسطة Gorbit إذا لم يتم توفيره
    * `sections`: قائمة أقسام المحتوى (راجع `TextSection` و `ImageSection`)
    * `source`: النظام الذي نشأ منه هذا المستند (راجع `DocumentSource`)
    * `semantic_identifier`: يُعرض في الواجهة كاسم المستند
    * `metadata`: `string` أو `list[string]` عشوائي سيتم حفظه كوسوم لهذا المستند
    * `doc_updated_at`: طابع زمني UTC عندما تم تحديث المستند آخر مرة
    * `chunk_count`: عدد القطع التي تم تقسيم المستند إليها للمعالجة
    * `primary_owners`: بيانات وصفية عن الأشخاص المرتبطين بالمستند
    * `secondary_owners`: بيانات وصفية عن الأشخاص المرتبطين بالمستند
    * `title`: يُستخدم للبحث (افتراضياً `semantic_identifier` إذا لم يتم تحديده)
    * `from_ingestion_api`: ما إذا كان هذا المستند قادماً من Ingestion API
    * `additional_info`: معلومات خاصة بالموصل قد تحتاجها أجزاء أخرى من الكود
    * `external_access`: بيانات مزامنة الأذونات (نسخة Enterprise فقط)

    <Note>
      توسع Ingestion API تعريف DocumentBase لتشمل `cc_pair_id` لربط
      مستند تلقائياً بـ CC-pair.
    </Note>

    ```python Python expandable theme={null}
    class DocumentBase(BaseModel):
      """تُستخدم لـ Gorbit ingestion api، يتم استنتاج ID قبل الاستخدام إذا لم يتم توفيره"""

      id: str | None = None
      sections: list[TextSection | ImageSection]
      source: DocumentSource | None = None
      semantic_identifier: str
      metadata: dict[str, str | list[str]]

      doc_updated_at: datetime | None = None
      chunk_count: int | None = None

      primary_owners: list[BasicExpertInfo] | None = None
      secondary_owners: list[BasicExpertInfo] | None = None
      title: str | None = None
      from_ingestion_api: bool = False
      additional_info: Any = None

      external_access: ExternalAccess | None = None
    ```
  </Accordion>

  <Accordion title="DocumentSource" icon="file">
    `DocumentSource` هو تعداد يحدد المصادر الصالحة للمستند.
    يتطلب رفع الملفات إلى Ingestion API وإنشاء `Connectors` برمجياً تحديد
    `DocumentSource`.

    ```python Python expandable theme={null}
    class DocumentSource(str, Enum):
      INGESTION_API = "ingestion_api"     # حالة خاصة، مستند تم تمريره عبر Gorbit APIs بدون تحديد نوع المصدر
      SLACK = "slack"
      WEB = "web"
      GOOGLE_DRIVE = "google_drive"
      GMAIL = "gmail"
      REQUESTTRACKER = "requesttracker"
      GITHUB = "github"
      GITBOOK = "gitbook"
      GITLAB = "gitlab"
      GURU = "guru"
      BOOKSTACK = "bookstack"
      CONFLUENCE = "confluence"
      JIRA = "jira"
      SLAB = "slab"
      PRODUCTBOARD = "productboard"
      FILE = "file"
      NOTION = "notion"
      ZULIP = "zulip"
      LINEAR = "linear"
      HUBSPOT = "hubspot"
      DOCUMENT360 = "document360"
      GONG = "gong"
      GOOGLE_SITES = "google_sites"
      ZENDESK = "zendesk"
      LOOPIO = "loopio"
      DROPBOX = "dropbox"
      SHAREPOINT = "sharepoint"
      TEAMS = "teams"
      SALESFORCE = "salesforce"
      DISCOURSE = "discourse"
      AXERO = "axero"
      CLICKUP = "clickup"
      MEDIAWIKI = "mediawiki"
      WIKIPEDIA = "wikipedia"
      ASANA = "asana"
      S3 = "s3"
      R2 = "r2"
      GOOGLE_CLOUD_STORAGE = "google_cloud_storage"
      OCI_STORAGE = "oci_storage"
      XENFORO = "xenforo"
      NOT_APPLICABLE = "not_applicable"
      DISCORD = "discord"
      FRESHDESK = "freshdesk"
      FIREFLIES = "fireflies"
      EGNYTE = "egnyte"
      AIRTABLE = "airtable"
      HIGHSPOT = "highspot"

      IMAP = "imap"

      # حالة خاصة فقط لاختبارات التكامل
      MOCK_CONNECTOR = "mock_connector"
    ```
  </Accordion>

  <Accordion title="TextSection" icon="text">
    `TextSection` هي جزء من مستند في Gorbit.

    * `text`: المحتوى النصي الفعلي للقسم
    * `link`: URL اختياري يتعلق به قسم النص هذا أو مصدر منه

    ```python Python theme={null}
    class TextSection(Section):
      text: str
      link: str | None = None
    ```
  </Accordion>

  <Accordion title="ImageSection" icon="image">
    `ImageSection` هي صورة مستخرجة من مستند في Gorbit.

    * `image_file_id`: UUID لملف الصورة المخزن في مخزن ملفات Gorbit
    * `text`: وصف نصي اختياري أو تعليق للصورة
    * `link`: URL اختياري تتعلق به قسم الصورة هذا أو مصدر منه

    ```python Python theme={null}
    class ImageSection(Section):
      image_file_id: str
      text: str | None = None
      link: str | None = None
    ```
  </Accordion>

  <Accordion title="AccessType" icon="shield">
    `AccessType` يحدد من يمكنه الوصول إلى البيانات من `Connector` في Gorbit.

    * `PUBLIC`: يمكن لجميع مستخدمي Gorbit الوصول إلى البيانات من هذا `Connector`
    * `PRIVATE`: فقط المستخدم الذي أنشأ `Connector` والمجموعات المحددة يمكنهم الوصول إلى البيانات من هذا `Connector`
    * `SYNC`: فقط `Connectors` مع دعم مزامنة الأذونات يمكن ضبطها على SYNC. سيقوم `Connector` بمزامنة أذونات الوصول مع النظام المصدر.

    ```python Python theme={null}
    class AccessType(str, Enum):
      PUBLIC = "public"
      PRIVATE = "private"
      SYNC = "sync"
    ```
  </Accordion>

  <Accordion title="InputType" icon="gear">
    `InputType` يحدد كيف يسترجع `Connector` البيانات من نظام المصدر الخاص به.

    * `LOAD_STATE`: تحميل واحد للبيانات من المصدر
    * `POLL`: استطلاع مستمر للبيانات الجديدة من المصدر (يبدأ بتحميل كامل)
    * `EVENT`: غير مطبق لمعظم `Connectors`
    * `SLIM_RETRIEVAL`: لـ `Connectors` مع مزامنة الأذونات

    ```python Python theme={null}
    class InputType(str, Enum):
      LOAD_STATE = "load_state"
      POLL = "poll"
      EVENT = "event"
      SLIM_RETRIEVAL = "slim_retrieval"
    ```
  </Accordion>
</AccordionGroup>

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

<CardGroup cols={2}>
  <Card title="دليل: فهرسة الملفات باستخدام Ingestion API" icon="lightbulb" href="/developers/guides/index_files_ingestion_api">
    تعلم كيفية فهرسة الملفات باستخدام Ingestion API
  </Card>

  <Card title="دليل: إرسال رسالة محادثة" icon="comment" href="/developers/guides/chat_guide">
    مثال بسيط على إرسال رسالة برمجياً
  </Card>
</CardGroup>