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 मोड** गहन, बहु-चरणीय निवेश अनुसंधान के लिए। मजबूत तर्कशक्ति बहु-चरणीय विश्लेषण को संचालित करती है जहां एजेंट अपने दृष्टिकोण की योजना बनाता है, वित्तीय डेटा पर विचार करता है, और जटिल विश्लेषण के लिए कोड लिखता है। लंबा संदर्भ इसे एक ही पास में SEC फाइलिंग और शोध रिपोर्ट को क्रॉस-रेफरेंस करने देता है।
- **फ्लैश मोड** तेज संवादात्मक प्रतिक्रियाओं और कार्यक्षेत्र ऑर्केस्ट्रेशन के लिए: त्वरित बाजार खोज, MarketView में चार्ट-एंड-चैट, हल्का Q&A, और एक सचिव जो कार्यक्षेत्रों का प्रबंधन करता है, पृष्ठभूमि में गहन PTC विश्लेषण भेजता है, और प्राकृतिक वार्तालाप के माध्यम से परिणाम वापस भेजता है।

**अपना मॉडल लाएँ** — अपनी मौजूदा AI सदस्यताओं और API कुंजियों का सीधे उपयोग करें। ChatGPT या Claude सदस्यताओं को OAuth (OpenAI Codex OAuth, Claude Code OAuth) के माध्यम से कनेक्ट करें, Kimi (Moonshot), GLM (Zhipu), MiniMax, या Doubao (Volcengine) से कोडिंग योजनाओं का उपयोग करें, या BYOK के माध्यम से किसी भी समर्थित प्रदाता के लिए अपनी स्वयं की API कुंजियाँ प्रदान करें। सभी कुंजियाँ PostgreSQL pgcrypto के माध्यम से आराम से एन्क्रिप्ट की जाती हैं (देखें [सुरक्षा](#security))।

**मॉडल लचीलापन** — क्षणिक त्रुटियों पर स्वचालित पुनर्प्रयास, फिर एक कॉन्फ़िगर किए गए फ़ॉलबैक मॉडल पर फेलओवर। तर्कशक्ति प्रयास (`low`/`medium`/`high`) प्रदाताओं में स्वचालित रूप से सामान्यीकृत होता है।

### प्रोग्रामेटिक टूल कॉलिंग (PTC) और कार्यक्षेत्र संरचना

अधिकांश AI एजेंट एक बार के JSON टूल कॉल के माध्यम से डेटा के साथ बातचीत करते हैं जो परिणाम को सीधे संदर्भ विंडो में डंप करते हैं। प्रोग्रामेटिक टूल कॉलिंग इसे उलट देता है: कच्चे डेटा को 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()` टूल के माध्यम से समानांतर एसिंक्रोनस सबएजेंट उत्पन्न करता है। सबएजेंट पृथक संदर्भ विंडो (isolated context windows) के साथ समवर्ती रूप से निष्पादित होते हैं, जो लंबी तर्क शृंखलाओं में विचलन (drift) को रोकते हैं। प्रत्येक सबएजेंट मुख्य एजेंट को संश्लेषित परिणाम वापस भेजता है, जिससे ऑर्केस्ट्रेटर हल्का रहता है। मुख्य एजेंट किसी सबएजेंट के परिणाम की प्रतीक्षा करना या अन्य लंबित कार्य जारी रखना चुन सकता है। आप UI में **Subagents** दृश्य पर स्विच करके उनकी प्रगति रीयल टाइम में देख सकते हैं (केवल वेब फ्रंटएंड)।

सरल डिस्पैच से परे, मुख्य एजेंट अभी भी चल रहे सबएजेंट को अतिरिक्त निर्देश भेज सकता है, या किसी पूर्ण किए गए सबएजेंट को पूरे संदर्भ के साथ पुनः शुरू कर सकता है ताकि पुनरावृत्तीय सुधार (iterative refinement) हो सके। यदि सर्वर पुनः प्रारंभ होता है, तो सबएजेंट की स्थिति स्वचालित रूप से उसके अंतिम चेकपॉइंट से पुनर्निर्मित होती है।

<p align="center">
  <img src="https://assets.kitploit.com/production/public/readmes/13458/dd8d54f3a8879372cf72c8a05d6ecce70c53ed0d86c8aed6a49c49276d4f97e4.png" alt="डेटा सेंटर कंप्यूट चेन पर शोध कर रहे समानांतर सबएजेंट जिनमें इंटरएक्टिव AI कंप्यूट टाइमलाइन है" width="800" />
</p>
<p align="center"><em>शोध सबएजेंट कंप्यूट चेन के पार समानांतर चलते हैं — परिणाम एक इंटरएक्टिव AI कंप्यूट टाइमलाइन में विलीन हो जाते हैं जो NVIDIA, Google, AMD, AWS और बाकी उद्योग को कवर करती है।</em></p>

### मिडलवेयर स्टैक

एजेंट एक मिडलवेयर स्टैक के साथ आता है, जिसमें शामिल हैं:

- **लाइव स्टीयरिंग** — एजेंट गलत रास्ता ले सकते हैं, अप्रासंगिक डेटा का पीछा कर सकते हैं, या विश्लेषण के दौरान आपके इरादे को गलत समझ सकते हैं। स्टीयरिंग आपको बिना प्रतीक्षा किए पाठ्यक्रम सुधारने (course-correct) देता है। जब एजेंट काम कर रहा हो, किसी भी समय एक फॉलो-अप संदेश भेजें — अपडेटेड निर्देश, स्पष्टीकरण, या पूरी तरह से नए प्रश्न — और एजेंट इसे अपने अगले चरण से पहले उठा लेता है, जैसे आपने वास्तविक समय में कहा हो। स्टीयरिंग हर स्तर पर काम करता है: मुख्य एजेंट को पुनर्निर्देशित करें, व्यक्तिगत पृष्ठभूमि सबएजेंट को फॉलो-अप भेजें, या सिस्टम को अनुपयुक्त संदेशों को आपके इनपुट बॉक्स में वापस लाने दें यदि कार्यप्रवाह पहले समाप्त हो जाए। कोई कार्य खोता नहीं, कोई पुनर्प्रारंभ आवश्यक नहीं।
- **गतिशील कौशल लोडिंग** `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 पर स्ट्रीम करता है: टेक्स्ट चंक, तर्क और परिणामों सहित टूल कॉल, सबएजेंट स्थिति अपडेट, फ़ाइल ऑपरेशन आर्टिफैक्ट, और ह्यूमन-इन-द-लूप इंटरप्ट। प्रत्येक एजेंट निर्णय UI में पूरी तरह से ट्रेस करने योग्य होता है।

कार्यप्रवाह स्वतंत्र पृष्ठभूमि कार्यों के रूप में चलते हैं, 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 संदर्भ में प्रवेश नहीं करता। UI इसे प्रत्येक दौर के बगल में एक Sources पैनल के रूप में प्रस्तुत करता है: प्रकार के अनुसार समूहीकृत स्रोत, वेब मूल के लिए फ़ेविकॉन, और एक विवरण दृश्य जो प्रदाता, टाइमस्टैम्प, कैप्चर किए गए तर्क, एक सामग्री फिंगरप्रिंट और एक स्निपेट को उजागर करता है। एक *This turn / All sources* टॉगल पूरे थ्रेड में डेटा फुटप्रिंट प्रकट करता है, और किसी फ़ाइल या मेमो स्रोत पर क्लिक करने से वह सीधे वर्कस्पेस फ़ाइल पैनल में खुलता है — प्रत्येक शोध आउटपुट के पीछे डेटा का एक पूरी तरह से लेखापरीक्षा योग्य निशान।

## सुरक्षा और वर्कस्पेस वॉल्ट

LangAlpha क्रेडेंशियल्स, कोड निष्पादन और उपयोगकर्ता-आपूर्ति रहस्यों में एक स्तरित सुरक्षा मॉडल लागू करता है।

**आराम पर एन्क्रिप्शन** — सभी संवेदनशील डेटा (BYOK API कुंजियाँ, OAuth टोकन, वॉल्ट रहस्य) `pgcrypto` का उपयोग करके PostgreSQL के अंदर एन्क्रिप्ट किया जाता है। प्लेनटेक्स्ट कभी डेटाबेस में संग्रहीत नहीं होता।

**क्रेडेंशियल लीक डिटेक्शन** — प्रत्येक टूल आउटपुट LLM संदर्भ तक पहुँचने से पहले स्कैन किया जाता है। मिडलवेयर सभी ज्ञात गुप्त मानों (MCP सर्वर कुंजियाँ, सैंडबॉक्स टोकन, वॉल्ट रहस्य) को हल करता है और किसी भी मिलान को `[REDACTED:KEY_NAME]` के रूप में रिडैक्ट करता है। वही रिडैक्शन मानव-सामने वाली सतहों पर लागू होता है — क्लाइंट तक पहुँचने से पहले फ़ाइल रीड और डाउनलोड को साफ़ कर दिया जाता है।

**सैंडबॉक्स कोड निष्पादन** — प्रत्येक वर्कस्पेस अपने स्वयं के [Daytona](https://www.daytona.io/) क्लाउड सैंडबॉक्स में एक समर्पित फाइलसिस्टम और नेटवर्क सीमा के साथ चलता है। संरक्षित पथ रक्षक (Protected path guards) एजेंट को आंतरिक सिस्टम निर्देशिकाओं तक पहुँचने से रोकते हैं — टूल इनपुट (निष्पादन से पहले कॉल को शॉर्ट-सर्किट करना) और टूल आउटपुट (लीक हुए पथों को रिडैक्ट करना) दोनों को अवरुद्ध करते हैं।

### वर्कस्पेस वॉल्ट

प्रत्येक वर्कस्पेस में API कुंजियों और क्रेडेंशियल्स को संग्रहीत करने के लिए एक अंतर्निहित सीक्रेट वॉल्ट होता है जिसका उपयोग एजेंट कोड निष्पादन के दौरान कर सकता है — तृतीय-पक्ष डेटा स्रोतों (ब्रोकरेज API, बाहरी डेटा विक्रेता, आदि) तक पहुँचने या वर्कस्पेस के अंदर LLM-संचालित कार्यप्रवाह बनाने के लिए उपयोगी। एक बार UI में कोई रहस्य संग्रहीत करें, और यह एक सरल Python API के माध्यम से उस वर्कस्पेस में प्रत्येक एजेंट सत्र के लिए उपलब्ध होता है:```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)
- **बैकएंड API:** [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`                        | उच्च-गुणवत्ता वाले फंडामेंटल्स, मैक्रो, SEC फाइलिंग, ऑप्शन ([निःशुल्क स्तर उपलब्ध](https://site.financialmodelingprep.com/)) |
| `SERPER_API_KEY` या `TAVILY_API_KEY` | वेब खोज                                                                                                              |
| `LANGSMITH_API_KEY`                  | LangGraph रन के लिए LangSmith ट्रेसिंग                                                                            |
| `OTEL_EXPORTER_OTLP_ENDPOINT`        | किसी भी OTLP बैकएंड (Jaeger, Grafana Tempo, Datadog, Honeycomb, ...) पर OpenTelemetry ट्रेस और मीट्रिक                   |
| `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) देखें।

## दस्तावेज़ीकरण

- **[API संदर्भ](https://github.com/ginlix-ai/langalpha/blob/HEAD/docs/api/README.md)** चैट स्ट्रीमिंग, वर्कस्पेस, वर्कफ़्लो स्थिति और अधिक के एंडपॉइंट के साथ
- **इंटरैक्टिव API डॉक्स** सर्वर चलने पर `http://localhost:8000/docs` पर

## संपर्क

साझेदारी, सहयोग या सामान्य पूछताछ के लिए, [[email protected]](mailto:[email protected]) पर संपर्क करें।

## अस्वीकरण

LangAlpha एक शोध उपकरण है, कोई वित्तीय सलाहकार नहीं। इस सॉफ्टवेयर द्वारा उत्पन्न कोई भी चीज़ निवेश सलाह, सिफारिश या किसी प्रतिभूति को खरीदने या बेचने का निमंत्रण नहीं है। सभी आउटपुट केवल सूचनात्मक और शैक्षिक उद्देश्यों के लिए हैं। अपने विवेक से उपयोग करें — निवेश निर्णय लेने से पहले हमेशा अपना स्वयं का उचित परिश्रम करें।

## लाइसेंस

Apache License 2.0