LangAlpha

subgraph Server ["FastAPI Backend"]
    API["API Routers<br/>Threads · Workspaces · Market Data<br/>OAuth · Automations · Skills"]
    WSP["WebSocket Proxy"]
    API --> ChatHandler["Chat Handler<br/>LLM Resolution · Workflow Dispatch"]
    ChatHandler --> BTM["Background Task Manager<br/>Decoupled Execution · Workflow Lifecycle"]
end

subgraph PostgreSQL ["PostgreSQL — Dual Pool"]
    AppPool[("App Data<br/>Users · Workspaces · Threads<br/>Turns · BYOK Keys · Automations")]
    CheckPool[("LangGraph Checkpointer<br/>Agent State · Checkpoints")]
end

subgraph Redis ["Redis"]
    EventBuf[("SSE Event Buffer<br/>150K events · Reconnect Replay")]
    DataCache[("API Cache<br/>Market Data · SWR")]
    Steering[("Steering Queue<br/>User Messages Mid-workflow")]
end

BTM --> AppPool
BTM --> CheckPool
BTM --> EventBuf
BTM --> Steering
API --> DataCache

BTM -. "Sandbox API" .-> Daytona["Daytona<br/>Cloud Sandboxes"]
API -. "REST" .-> FinAPIs["Financial APIs<br/>FMP · SEC EDGAR"]
WSP -. "WebSocket" .-> GData["ginlix-data<br/>Polygon.io · Massive"]

### طبقة النماذج متعددة المزودين

يعمل LangAlpha على طبقة نماذج غير مرتبطة بمزود معين، تُجرد عبر واجهات خلفية متعددة للـ LLM. تعمل نفس مجموعة الوسائط البرمجية، الأدوات، وسير العمل بغض النظر عن النموذج الذي يقوم بتشغيلها. يأتي مع وضعين:

- **وضع PTC** للبحث الاستثماري العميق متعدد الخطوات. يدفع الاستدلال القوي التحليل متعدد الخطوات حيث يخطط الوكيل لنهجه، ويفكر في البيانات المالية، ويكتب كودًا للتحليل المعقد. السياق الطويل يتيح الرجوع إلى إيداعات هيئة الأوراق المالية وتقارير البحث في مسار واحد.
- **وضع Flash** للردود السريعة في المحادثة وتنسيق مساحات العمل: استعلامات سوقية سريعة، الرسم البياني والدردشة في MarketView، أسئلة وأجوبة خفيفة، وسكرتير يدير مساحات العمل، ويُرسل تحليلات PTC العميقة في الخلفية، ويعيد النتائج عبر محادثة طبيعية.

**احضر نموذجك الخاص** — استخدم اشتراكاتك الحالية في الذكاء الاصطناعي ومفاتيح API مباشرة. يمكنك ربط اشتراكات ChatGPT أو Claude عبر OAuth (OpenAI Codex OAuth، Claude Code OAuth)، أو استخدام خطط البرمجة من Kimi (Moonshot)، GLM (Zhipu)، MiniMax، أو Doubao (Volcengine)، أو توفير مفاتيح API الخاصة بك لأي مزود مدعوم عبر BYOK. جميع المفاتيح مشفرة في حالة السكون عبر PostgreSQL pgcrypto (راجع [الأمان](#security)).

**مرونة النموذج** — إعادة محاولة تلقائية عند الأخطاء المؤقتة، ثم التحويل إلى نموذج بديل مُكوّن. يتم توحيد جهد الاستدلال (`منخفض`/`متوسط`/`عالي`) عبر المزودين تلقائيًا.

### الاستدعاء البرمجي للأدوات (PTC) وهندسة مساحات العمل

تتفاعل معظم وكلاء الذكاء الاصطناعي مع البيانات من خلال استدعاءات أدوات JSON فردية تُفرغ النتيجة مباشرة في نافذة السياق. يعكس الاستدعاء البرمجي للأدوات (PTC) هذا: بدلاً من تمرير البيانات الخام عبر LLM، يكتب الوكيل وينفذ الكود داخل صندوق رمل سحابي [Daytona](https://www.daytona.io/) يعالج البيانات محليًا ويعيد فقط النتيجة النهائية. هذا يقلل بشكل كبير من هدر الرموز المميزة مع تمكين تحليل كان سيتجاوز حدود السياق.

**سير تنفيذ PTC**```mermaid
%%{init: {'theme': 'neutral'}}%%

flowchart LR
    LLM["LLM"] -- "1 — Writes Python" --> EC["ExecuteCode Tool"]
    EC -- "2 — Sends to sandbox" --> Run["Code Runner"]

    subgraph Sandbox ["Daytona Cloud Sandbox"]
        Run -- "3 — import tools.*" --> Wrappers["Generated Wrappers<br/>One module per MCP server"]
        Wrappers -- "4 — JSON-RPC stdio" --> MCP["MCP Servers<br/>Subprocesses in sandbox"]
    end

    MCP -- "5 — REST / WS" --> APIs["Financial APIs<br/>FMP · Yahoo · Polygon"]
    APIs -- "6 — Data" --> MCP
    Run -- "7 — stdout · charts · files" --> EC
    EC -- "8 — Result" --> LLM

Agent -- "Task(init · update · resume)" --> SubPool
SubPool -- "results" --> Orchestrator

subgraph SubPool ["Subagent Pool — Parallel Async"]
    direction LR
    S1["general-purpose"]
    S2["research"]
    S3["user-defined"]
end

subgraph Middleware ["Middleware Stack"]
    direction LR
    MW1["Tool Safety<br/>Leak Detection<br/>Protected Paths<br/>Error Handling"]
    MW2["Context & Skills<br/>agent.md Injection<br/>Skill Loading<br/>Multimodal"]
    MW3["Coordination<br/>HITL · Plan Mode<br/>Steering<br/>Subagent Dispatch"]
    MW4["Resilience<br/>Compaction<br/>Retry + Fallback<br/>Prompt Caching"]
end

Agent -- "wraps model + tool calls" --> Middleware
Middleware --> LLM["Multi-Provider LLM<br/>OpenAI · Anthropic · Gemini · DeepSeek<br/>Qwen · Kimi · Doubao · GLM · MiniMax · ..."]

Agent <--> Tools

subgraph Tools ["Tool Layer"]
    direction LR
    T1["execute_code<br/>bash"]
    T2["Filesystem<br/>read · write · edit<br/>glob · grep"]
    T3["Finance<br/>Market Data · SEC<br/>Options · Screener"]
    T4["Web<br/>Search · Fetch"]
    T5["ShowWidget<br/>Inline HTML"]
end

T1 <--> Workspace
T2 <--> Workspace

subgraph Workspace ["Workspace — Daytona Sandbox"]
    direction LR
    W1["agent.md<br/>Workspace Notes"]
    W2["work/‹task›/<br/>data · charts"]
    W3["results/<br/>Reports"]
    W4["tools/<br/>MCP Wrappers"]
end

### سرب الوكلاء

الوكيل الأساسي يعمل على [LangGraph](https://github.com/langchain-ai/langgraph) ويطلق وكلاء فرعيين غير متزامنين بالتوازي عبر أداة `Task()`. ينفذ الوكلاء الفرعيون بشكل متزامن مع نوافذ سياق معزولة، مما يمنع الانحراف في سلاسل التفكير الطويلة. يعيد كل وكيل فرعي النتائج المُجمَّعة إلى الوكيل الرئيسي، مما يحافظ على خفة المُنسِّق. يمكن للوكيل الرئيسي اختيار انتظار نتيجة وكيل فرعي أو مواصلة أعمال أخرى معلقة. يمكنك أيضًا التبديل إلى عرض **الوكلاء الفرعيين** في واجهة المستخدم لرؤية تقدمهم في الوقت الفعلي (واجهة ويب فقط).

إلى جانب الإرسال البسيط، يمكن للوكيل الرئيسي إرسال تعليمات متابعة إلى وكيل فرعي لا يزال قيد التشغيل، أو استئناف وكيل فرعي مكتمل مع السياق الكامل للتحسين التكراري. إذا تم إعادة تشغيل الخادم، يتم إعادة بناء حالة الوكيل الفرعي تلقائيًا من آخر نقطة تفتيش له.

<p align="center">
  <img src="https://assets.kitploit.com/production/public/readmes/13458/dd8d54f3a8879372cf72c8a05d6ecce70c53ed0d86c8aed6a49c49276d4f97e4.png" alt="وكلاء فرعيون متوازيون يبحثون في سلسلة حوسبة مركز البيانات مع مخطط زمني تفاعلي لحوسبة الذكاء الاصطناعي" width="800" />
</p>
<p align="center"><em>يعمل الوكلاء الفرعيون للبحث بالتوازي عبر سلسلة الحوسبة — تندمج النتائج في مخطط زمني تفاعلي لحوسبة الذكاء الاصطناعي يغطي NVIDIA وGoogle وAMD وAWS وباقي الصناعة.</em></p>

### مجموعة البرامج الوسيطة

يأتي الوكيل مع مجموعة من البرامج الوسيطة، تتضمن:

- **التوجيه المباشر** — يمكن للوكلاء أن يسلكوا منعطفات خاطئة، أو يتبعوا بيانات غير ذات صلة، أو يسيئوا فهم نيتك أثناء التحليل. يتيح لك التوجيه تصحيح المسار دون انتظار. أرسل رسالة متابعة في أي وقت أثناء عمل الوكيل — تعليمات محدثة، توضيحات، أو أسئلة جديدة كليًا — ويلتقطها الوكيل قبل خطوته التالية، وكأنك قلتها في الوقت الفعلي. يعمل التوجيه على كل المستويات: إعادة توجيه الوكيل الرئيسي، إرسال متابعات لوكلاء فرعيين فرديين في الخلفية، أو السماح للنظام بإعادة الرسائل غير المستهلكة بلطف إلى مربع الإدخال الخاص بك إذا انتهى سير العمل أولاً. لا يُفقد أي عمل، ولا حاجة لإعادة التشغيل.
- **تحميل المهارات الديناميكي** عبر أداة `LoadSkill` التي تتيح للوكيل اكتشاف وتفعيل مجموعات أدوات المهارات عند الطلب، مما يحافظ على سطح الأدوات الافتراضي خفيفًا مع إتاحة القدرات المتخصصة عند الحاجة.
- **متعدد الوسائط** يعترض قراءة الملفات للصور وملفات PDF، ويحمل المحتوى من البيئة الرملية أو عناوين URL، ويحقنه كـ base64 في المحادثة لتتمكن النماذج متعددة الوسائط من تفسيرها بشكل أصلي.
- **وضع التخطيط** مع مقاطعات الإشراف البشري يتيح لك مراجعة استراتيجية الوكيل والموافقة عليها قبل التنفيذ.
- **الضغط التلقائي** يضغط تاريخ المحادثة عند الاقتراب من حدود الرموز، مع الحفاظ على السياق الرئيسي مع توفير المساحة.
- **إدارة السياق** تقوم تلقائيًا بتفريغ نتائج الأدوات الكبيرة إلى نظام ملفات مساحة العمل، مع الاحتفاظ بمعاينة قصيرة في السياق، وتضغط المحادثات الطويلة مع نموها — تلخص الجولات الأقدم مع إبقاء النص الكامل قابلاً للاسترداد في مساحة العمل. يمكن أن تعمل جلسات البحث إلى أجل غير مسمى دون الوصول إلى حدود السياق.

انظر [`src/ptc_agent/agent/middleware/`](https://github.com/ginlix-ai/langalpha/blob/HEAD/src/ptc_agent/agent/middleware/) للمجموعة الكاملة.

إقرار: بعض مكونات البرامج الوسيطة مقتبسة أو مستوحاة من التطبيق في [LangChain DeepAgents](https://github.com/langchain-ai/deepagents).

### البث والبنية التحتية

يقوم الخادم ببث جميع أنشطة الوكيل عبر SSE: أجزاء النص، استدعاءات الأدوات مع الوسائط والنتائج، تحديثات حالة الوكيل الفرعي، آثار عمليات الملفات، ومقاطعات الإشراف البشري. كل قرار يتخذه الوكيل يمكن تتبعه بالكامل في واجهة المستخدم.

تعمل سير العمل كمهام خلفية مستقلة، منفصلة تمامًا عن اتصال HTTP/SSE. إذا تم إغلاق علامة التبويب في المتصفح أو انقطع الاتصال بالشبكة، يستمر الوكيل في العمل. عند إعادة الاتصال، يتم إعادة تشغيل ما يصل إلى 150,000 حدث مخزن مؤقتًا ليلتقط العميل من حيث توقف تمامًا.

يقوم PostgreSQL بدعم نقاط التفتيش الخاصة بـ LangGraph، وتاريخ المحادثة، وبيانات المستخدم (قوائم المراقبة، المحافظ، التفضيلات)، بحيث تستمر حالة الوكيل وسياق المستخدم عبر الجلسات. يقوم Redis بتخزين أحداث SSE مؤقتًا بحيث لا تؤدي تحديثات المتصفح وانقطاعات الشبكة إلى فقدان الرسائل أثناء الإرسال: يعيد العميل الاتصال ويعيد التشغيل تلقائيًا. يتم عرض بيانات المستخدم على الوكيل كملفات JSON افتراضية مدعومة مباشرة بقاعدة البيانات — تقوم عمليات القراءة بتسلسل الصفوف الحية عند الطلب وتطبق عمليات الكتابة في معاملة واحدة تم التحقق منها، دون رحلة ذهاب وإياب للمزامنة مع البيئة الرملية — بينما تتم مزامنة المهارات مع البيئة الرملية عند بدء الجلسة عبر ذاكرة تخزين مؤقت قائمة على البيان، ويتم إعادة تحميلها فقط عند تغييرها. راجع [مرجع API](https://github.com/ginlix-ai/langalpha/blob/HEAD/docs/api/README.md) الكامل للتفاصيل.

### تتبع المصادر

يتم تتبع كل مصدر بيانات خارجي يلمسه الوكيل وإظهاره. يسجل برنامج وسيط للتتبع كل بحث ويب، جلب صفحة، إيداع لدى SEC، استدعاء بيانات سوق، استدعاء أداة MCP، وقراءة ملف في مساحة العمل — بما في ذلك الوصول الذي تقوم به الوكلاء الفرعيون في الخلفية — ويصدر حدث دفق `provenance` لكل مصدر، ولا يدخل أي منها في سياق LLM. تقوم واجهة المستخدم بعرض هذه المصادر كلوحة مصادر بجانب كل جولة: مصادر مجمعة حسب النوع، أيقونات مفضلة للمواقع الإلكترونية، وعرض تفصيلي يكشف المزود، الطابع الزمني، الوسائط الملتقطة، بصمة محتوى، ومقتطف. مفتاح تبديل *هذه الجولة / جميع المصادر* يكشف عن بصمة البيانات الكاملة عبر سلسلة المحادثة بأكملها، والنقر على مصدر ملف أو مذكرة يفتحه مباشرة في لوحة ملفات مساحة العمل — مسار تدقيق كامل للبيانات وراء كل مخرج بحث.

## الأمان وخزانة مساحة العمل

يطبق LangAlpha نموذج أمان متعدد الطبقات عبر بيانات الاعتماد، تنفيذ الكود، والأسرار التي يوفرها المستخدم.

**التشفير عند التخزين** — يتم تشفير جميع البيانات الحساسة (مفاتيح API من نوع BYOK، رموز OAuth، أسرار الخزانة) داخل PostgreSQL باستخدام `pgcrypto`. لا يتم تخزين النص الصريح في قاعدة البيانات أبدًا.

**كشف تسرب بيانات الاعتماد** — يتم فحص كل مخرج من مخرجات الأدوات قبل وصوله إلى سياق LLM. تقوم البرامج الوسيطة بحل جميع قيم الأسرار المعروفة (مفاتيح خادم MCP، رموز البيئة الرملية، أسرار الخزانة) وتقوم بحذف أي تطابق كـ `[REDACTED:KEY_NAME]`. ينطبق نفس الحذف على الأسطح الموجهة للبشر — يتم تنظيف قراءات الملفات والتنزيلات قبل الوصول إلى العميل.

**تنفيذ الكود في بيئة رملية** — تعمل كل مساحة عمل في بيئة رملية سحابية خاصة بها [Daytona](https://www.daytona.io/) مع نظام ملفات وحدود شبكة مخصصة. تمنع حراس المسارات المحمية الوكيل من الوصول إلى أدلة النظام الداخلية — مما يمنع كل من إدخال الأداة (تقصير الاستدعاء قبل التنفيذ) وإخراج الأداة (حذف المسارات المسربة).

### خزانة مساحة العمل

تحتوي كل مساحة عمل على خزانة أسرار مدمجة لتخزين مفاتيح API وبيانات الاعتماد التي يمكن للوكيل استخدامها أثناء تنفيذ الكود — مفيدة للوصول إلى مصادر بيانات خارجية (واجهات برمجة تطبيقات الوساطة، موردي بيانات خارجيين، إلخ) أو بناء سير عمل مدعوم بـ LLM داخل مساحة العمل. قم بتخزين سر مرة واحدة في واجهة المستخدم، وسيكون متاحًا لكل جلسة وكيل في تلك المساحة عبر واجهة برمجة تطبيقات Python بسيطة:```python
from vault import get, list_names, load_env

api_key = get("MY_API_KEY")       # retrieve a single secret
names = list_names()               # list available secret names
load_env()                         # bulk-load all secrets as env vars

- **الواجهة الأمامية:** [http://localhost:5173](http://localhost:5173)
- **واجهة برمجة التطبيقات الخلفية:** [http://localhost:8000](http://localhost:8000) (وثائق تفاعلية على `/docs`)
- **التحقق:** `curl http://localhost:8000/health`

للحصول على التجربة الكاملة، سيطلب منك المعالج إدخال المفاتيح الاختيارية — أو يمكنك إضافتها إلى ملف `.env` لاحقًا:

| المفتاح                              | ما يوفره                                                                                                                 |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| `DAYTONA_API_KEY`                    | بيئات رملية سحابية دائمة مع دعم مساحات العمل عبر الجلسات ([daytona.io](https://www.daytona.io/))                         |
| `FMP_API_KEY`                        | بيانات أساسية عالية الجودة، بيانات الاقتصاد الكلي، إيداعات هيئة الأوراق المالية، خيارات ([النسخة المجانية متوفرة](https://site.financialmodelingprep.com/)) |
| `SERPER_API_KEY` أو `TAVILY_API_KEY` | البحث عبر الويب                                                                                                          |
| `LANGSMITH_API_KEY`                  | تتبع LangSmith لتشغيلات LangGraph                                                                                        |
| `OTEL_EXPORTER_OTLP_ENDPOINT`        | تتبع وقياسات OpenTelemetry إلى أي خلفية OTLP (Jaeger، Grafana Tempo، Datadog، Honeycomb، ...)                            |
| `SANDBOX_PROVIDER`                   | تجاوز مزود البيئة الرملية (`daytona` أو `docker`)؛ يتم اكتشافه تلقائيًا من `DAYTONA_API_KEY` عندما لا يكون مضبوطًا        |

> [!NOTE]
> بدون مفاتيح الخدمات الخارجية ستحصل على تجربة وظيفية ولكنها محدودة: توفر Yahoo Finance بيانات تاريخية مجانية للأسعار والأساسيات والأرباح وتحليلات المحللين، ولكنها تفتقر إلى الأسعار اللحظية وبيانات التداول اليومية والاقتصاد الكلي وتحليلات الخيارات. تحل البيئة الرملية Docker محل البيئات الرملية السحابية Daytona — يعمل تنفيذ كود PTC الكامل، ولكن مع أمان وعزل أقل. أضف المفاتيح تدريجيًا لفتح المزيد من الإمكانيات.

قم بتشغيل `make help` لرؤية جميع الأوامر المتاحة. للإعداد اليدوي بدون Docker، راجع [CONTRIBUTING.md](https://github.com/ginlix-ai/langalpha/blob/HEAD/CONTRIBUTING.md#manual-setup).

## التوثيق

- **[مرجع واجهة برمجة التطبيقات](https://github.com/ginlix-ai/langalpha/blob/HEAD/docs/api/README.md)** مع نقاط نهاية لبث الدردشة ومساحات العمل وحالة سير العمل والمزيد
- **وثائق واجهة برمجة التطبيقات التفاعلية** على `http://localhost:8000/docs` عندما يكون الخادم قيد التشغيل

## الاتصال

للشراكات أو التعاون أو الاستفسارات العامة، تواصل مع [[email protected]](mailto:[email protected]).

## إخلاء المسؤولية

LangAlpha هي أداة بحثية، وليست مستشارًا ماليًا. لا يشكل أي شيء تنتجه هذه البرمجيات نصيحة استثمارية أو توصية أو طلبًا لشراء أو بيع أي ورقة مالية. جميع المخرجات هي لأغراض إعلامية وتعليمية فقط. استخدمها على مسؤوليتك الخاصة — قم دائمًا بإجراء العناية الواجبة الخاصة بك قبل اتخاذ أي قرارات استثمارية.

## الترخيص

ترخيص Apache 2.0