LangAlpha

%%{init: {'theme': 'neutral'}}%%

flowchart TB
    Web["Web UI<br/>React 19 · Vite · Tailwind"] -- "REST · SSE" --> API
    Web -- "WebSocket" --> WSP
    CLI["CLI / TUI"] -- "REST · SSE" --> API

    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 제출 서류와 연구 보고서를 상호 참조할 수 있습니다.
- **Flash 모드**: 빠른 대화형 응답과 워크스페이스 오케스트레이션을 위한 모드입니다. 빠른 시장 조회, MarketView의 차트 및 채팅, 가벼운 Q&A, 워크스페이스를 관리하고 백그라운드에서 심층 PTC 분석을 전송하며 결과를 자연스러운 대화를 통해 전달하는 비서 역할을 합니다.

**자체 모델 사용** — 기존 AI 구독과 API 키를 직접 사용하세요. OAuth(OpenAI Codex OAuth, Claude Code OAuth)를 통해 ChatGPT 또는 Claude 구독을 연결하고, Kimi(Moonshot), GLM(Zhipu), MiniMax, 또는 Doubao(Volcengine)의 코딩 플랜을 사용하거나, BYOK를 통해 지원되는 제공자의 자체 API 키를 제공하세요. 모든 키는 PostgreSQL pgcrypto를 통해 저장 시 암호화됩니다([보안](#security) 참조).

**모델 탄력성** — 일시적 오류 시 자동 재시도 후 설정된 대체 모델로 장애 조치합니다. 추론 노력(`low`/`medium`/`high`)은 제공자 간에 자동으로 정규화됩니다.

### 프로그래매틱 도구 호출(PTC) 및 워크스페이스 아키텍처

대부분의 AI 에이전트는 일회성 JSON 도구 호출을 통해 데이터와 상호 작용하여 결과를 직접 컨텍스트 창에 덤프합니다. Programmatic Tool Calling은 이를 뒤집습니다: 에이전트는 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
```
또한, 워크스페이스 환경은 단일 세션을 넘어 지속성을 제공합니다. 각 샌드박스는 구조화된 디렉터리 레이아웃을 갖습니다. — 작업별 작업 영역(데이터, 차트, 코드)을 위한 `work/<task>/`, 최종 보고서를 위한 `results/`, 공유 데이터셋을 위한 `data/` — 따라서 중간 결과가 세션 간에 유지됩니다. 루트에는 `agent.md` 가 있습니다. 이는 에이전트가 스레드 전반에 걸쳐 유지 관리하는 워크스페이스 노트 파일로, 워크스페이스 목표, 주요 발견 사항, 스레드 인덱스 및 중요한 아티팩트의 파일 인덱스를 포함합니다. 미들웨어 계층이 모든 모델 호출에 `agent.md`를 주입하므로 에이전트는 파일을 다시 읽지 않고도 이전 작업의 전체 컨텍스트를 항상 알 수 있습니다. 이와 별도로, 저장소 기반 장기 기억 시스템(`.agents/user/memory/`, `.agents/workspace/memory/`)은 워크스페이스 초기화 후에도 유지되는 지속적인 사용자 선호도와 샌드박스 간 지식을 캡처하며, 사용자 관리 메모 저장소(`.agents/user/memo/`)는 업로드된 문서를 보관합니다. — PDF는 서버 측에서 텍스트가 추출되고 LLM에 의해 비동기적으로 메타데이터가 생성되어 에이전트가 주제별로 찾고 인용할 수 있습니다. 각 워크스페이스는 단일 연구 목표에 연결된 여러 대화 스레드를 지원합니다.

<p align="center">
  <img src="https://assets.kitploit.com/production/public/readmes/13458/0c53cdc0a2d703d01cdf7670109e29e7763df554d27fb8c1c3576fd0c7e5352e.png" alt="Workspaces page with research workspace cards" width="800" />
</p>
<p align="center"><em>각 워크스페이스는 지속성 있는 샌드박스에 매핑됩니다. — 주제, 포트폴리오 또는 논제별로 연구를 구성하세요.</em></p>

<p align="center">
  <img src="https://assets.kitploit.com/production/public/readmes/13458/8860e6c240041a9d1cc2711a81797217437a64535fba2577d435320c6fedbfc5.png" alt="PTC agent generating a Mag 7 + Semiconductors catalyst calendar dashboard" width="800" />
</p>
<p align="center"><em>에이전트는 코드를 작성하여 대화형 대시보드를 구축합니다. — 여기서는 Mag 7 + 반도체 촉매제 캘린더입니다.</em></p>

### 금융 데이터 생태계

PTC는 다단계 데이터 처리, 금융 모델링, 차트 생성과 같은 복잡한 작업에 탁월하지만 모든 데이터 조회에 코드 실행을 시작하는 것은 과도합니다. 따라서 자주 사용되는 데이터를 LLM이 소화하기 쉬운 형식으로 변환하는 네이티브 금융 데이터 도구 세트도 구축했습니다. 이러한 도구에는 프론트엔드에서 직접 렌더링되는 아티팩트도 함께 제공되어 인간 계층이 에이전트의 분석과 함께 즉각적인 시각적 컨텍스트를 얻을 수 있습니다.

**네이티브 도구** — 직접 도구 호출을 통한 빠른 참조:

- **회사 개요** — 실시간 시세, 가격 성과, 주요 재무 지표, 애널리스트 컨센서스, 매출 분석
- **SEC 제출 서류**(10-K, 10-Q, 8-K) — 실적 발표 녹취록 및 인용을 위한 형식화된 마크다운 포함
- **시장 지수** 및 **섹터 성과** — 광범위한 시장 컨텍스트 제공
- **웹 검색**(Tavily, Serper, Bocha) — 계층적 깊이(빠른 조회에서 심층 연구까지)가 있는 매니페스트 기반 공급자 선택, 이미지 검색 및 AI 연구 모드(사용자별 선택 가능) — 그리고 **웹 크롤링**(회로 차단기 내결함성 포함)

**MCP 서버** — PTC 코드 실행을 통해 소비되는 원시 데이터:

- **가격 데이터** — 주식, 상품, 암호화폐, 외환에 걸친 OHLCV 시계열, 공매도 잔고 및 공매도 거래량 분석
- **기초 데이터** — 다년간 재무제표, 비율, 성장 지표, 가치 평가, 임원 거래, 배당금 및 주식 분할, 유통 주식 수, 주요 임원, 기술적 지표
- **매크로 경제** — GDP, CPI, 실업률, 연준 금리, 국채 수익률 곡선(1M–30Y), 국가 위험 프리미엄, 경제 캘린더, 실적 캘린더
- **옵션** — 필터링이 있는 옵션 체인, 옵션 계약의 과거 OHLCV, 실시간 매수/매도 호가 스냅샷
- **Yahoo Finance 스위트**(가격, 기초, 분석, 시장) — 재무제표, 애널리스트 등급, 보유자, 스크리닝, 캘린더에 대한 키 없는 커버리지
- **X (Twitter)** 읽기 전용 게시물 검색, 사용자/트윗 조회, 스레드 가져오기(감정 및 이벤트 추적용), 추가로 JS 렌더링 및 안티봇 보호 페이지를 위한 **스크래핑** 서버

에이전트는 적절한 계층을 자동으로 선택합니다. 네이티브 도구는 컨텍스트에 맞는 빠른 조회용이고, MCP 도구는 작업에 대량 데이터 처리, 차트 작성 또는 샌드박스 내 다년간 추세 분석이 필요한 경우 사용됩니다.

MCP 서버는 워크스페이스별로 구성 가능합니다. 기본 제공 서버는 개별적으로 비활성화할 수 있으며, [워크스페이스 볼트](#workspace-vault)에서 자격 증명을 읽는 서버를 포함한 사용자 정의 HTTP 또는 stdio 서버는 API 또는 UI를 통해 추가할 수 있으며, 재시작 없이 몇 초 내에 적용됩니다.

#### 데이터 공급자 폴백 체인

LangAlpha는 3계층 데이터 공급자 계층 구조를 지원합니다. 각 계층은 선택 사항입니다. — 시스템은 상위 계층을 사용할 수 없을 때 정상적으로 성능이 저하됩니다.

| 계층 | 공급자                           | 필요한 키            | 추가 기능                                                                                      |
| ---- | --------------------------------- | ----------------- | ------------------------------------------------------------------------------------------ |
| 1    | **ginlix-data** (호스팅 프록시)    | `GINLIX_DATA_URL` | 실시간 WebSocket 가격 피드, 장중 데이터, 시간외 거래 데이터, 옵션 데이터                          |
| 2    | **FMP** (Financial Modeling Prep) | `FMP_API_KEY`     | 고품질 기초 데이터, 재무제표, 매크로 데이터, 애널리스트 데이터                                  |
| 3    | **Yahoo Finance** (yfinance)      | *없음 — 무료*       | 가격 내역, 기본 기초 데이터, 실적, 보유 내역, 내부자 거래, ESG, 스크리너                        |

모든 계층은 기본적으로 활성화됩니다. **무료 데이터만**(Yahoo Finance)으로 실행하려면 `make config`를 실행하고 프롬프트에서 선택하십시오. `agent_config.yaml`을 수동으로 편집할 수도 있습니다.

> [!NOTE]
> Yahoo Finance 데이터는 커뮤니티 기반이며 제한 사항이 있습니다. 1시간 간격 미만의 장중 데이터 없음, 지연된 시세, 제한된 매크로 범위, 간헐적인 속도 제한이 있습니다. `FMP_API_KEY`를 적극 권장합니다([무료 계층 사용 가능](https://site.financialmodelingprep.com/)).

### 금융 연구 기술

에이전트에는 23개의 사전 구축된 금융 연구 기술이 함께 제공되며, 각 기술은 슬래시 명령 또는 자동 감지로 활성화할 수 있습니다. 기술은 [Agent Skills Spec](https://agentskills.io/specification)을 따르며 `SKILL.md` 파일을 워크스페이스에 떨어뜨려 확장할 수 있습니다.

| 카테고리                 | 기술                                                                                         |
| ------------------------ | ------------------------------------------------------------------------------------------ |
| **가치 평가 및 모델링**     | DCF 모델, 비교 분석, 3-재무제표 모델, 모델 업데이트, 모델 감사                                |
| **주식 연구**              | 커버리지 개시(30–50쪽 보고서), 실적 프리뷰, 실적 분석, 논제 추적기                           |
| **시장 인텔리전스**        | 모닝 노트, 촉매제 캘린더, 섹터 개요, 경쟁 분석, 아이디어 생성, X 리서치                      |
| **문서 생성**              | PDF, DOCX, PPTX, XLSX, HTML — 생성, 편집, 추출                                                |
| **운영**                 | 투자 자료 QC, 예약된 자동화, 사용자 프로필 및 포트폴리오                                      |

감사의 말: 일부 기술은 [anthropics/financial-services-plugins](https://github.com/anthropics/financial-services-plugins)에서 각색되었습니다.

<p align="center">
  <img src="https://assets.kitploit.com/production/public/readmes/13458/a883b426561bd6be6ce52c41416e12f2d9afdc708a27e3f72750b732457c21e2.png" alt="NVDA, AMD, GOOGL에 대한 내재 가격 범위가 포함된 Excel 모델 및 PDF 가치 평가 보고서를 제공하는 비교분석 기술" width="800" />
</p>
<p align="center"><em>비교분석 기술은 동종 그룹 배수로부터 내재 가격 범위가 포함된 Excel 모델과 PDF 보고서를 제공합니다.</em></p>

### 멀티모달 인텔리전스

에이전트는 이미지(PNG, JPG, GIF, WebP)와 PDF를 기본적으로 읽습니다. — 멀티모달 미들웨어가 파일 읽기를 가로채 샌드박스 또는 URL에서 콘텐츠를 다운로드하고 base64로 대화에 주입하여 직접 시각적 해석을 가능하게 합니다. MarketView에서 사용자의 실시간 캔들스틱 차트를 캡처하여 에이전트에게 멀티모달 컨텍스트로 보낼 수 있습니다. — 캡처에는 차트 이미지와 구조화된 메타데이터(심볼, 간격, OHLCV, 이동 평균, RSI, 52주 범위)가 모두 포함되어 에이전트가 시각적 패턴과 기본 데이터 모두에 대해 추론할 수 있습니다.

<p align="center">
  <img src="https://assets.kitploit.com/production/public/readmes/13458/63afd08500cdb33e09e521a0dc0c672eba7ffa7426fa1a3ebd6bd3e351646a4e.png" alt="MarketView showing NVDA candlestick chart with AI support and resistance analysis" width="800" />
</p>
<p align="center"><em>MarketView는 실시간 차트를 에이전트에게 보내 실시간 기술적 분석을 수행합니다.</em></p>

### 에이전트 작성 차트 주석

에이전트에게 MarketView 차트에 표시를 요청하면 캔버스에 직접 그립니다. — 가격 수준, 추세선, 피보나치 되돌림, 이벤트 배지, 사각형 및 텍스트 마커. 주석은 SSE를 통해 실시간으로 스트리밍되고, 워크스페이스 및 `symbol:timeframe` 쌍별로 유지되며(예: `NVDA:1day`에 그린 그림은 `NVDA:1hour`와 별도로 유지됨), 재연결 시 재생됩니다. MarketView 외부에서 대화가 발생하면 채팅 기록에 주석 범례와 실시간 차트에 대한 원클릭 링크가 포함된 미리보기 카드가 표시됩니다. 차트 주석 기술은 MarketView에서 메시지가 전송될 때마다 자동으로 로드되므로 에이전트는 항상 "차트"가 참조하는 티커와 시간 프레임을 알 수 있습니다.

### 자동화

에이전트는 대화 내에서 자체 작업을 예약할 수 있습니다. — 별도의 UI가 필요하지 않습니다. 사용자는 전용 자동화 페이지에서 전체 CRUD, 실행 기록 및 수동 트리거를 통해 자동화를 관리할 수도 있습니다. 모든 자동화 유형은 동일한 `AutomationExecutor`, 구성 가능한 에이전트 모드(PTC 또는 Flash) 및 연속 실패 후 자동 비활성화를 공유합니다.

**시간 기반** — 표준 cron 표현식을 사용한 반복 일정("매주 월요일 오전 9시에 이 분석 실행") 및 단일 미래 실행을 위한 원샷 날짜/시간 예약.

**가격 트리거** — 주식 또는 주요 지수에 대한 가격 목표 또는 백분율 변동을 설정하면 조건이 충족되는 즉시 에이전트가 명령을 실행합니다. `PriceMonitorService`는 공유 업스트림 WebSocket 연결을 통해 [ginlix-data](https://github.com/ginlix-ai/ginlix-data)를 구독하여 실시간 틱을 수신합니다(주식은 실시간 계층, 지수는 지연 계층). Redis 기반 중복 제거는 서버 인스턴스 간에 중복 트리거를 방지합니다.

| 조건                          | 예시                                              |
| ----------------------------- | ------------------------------------------------- |
| 가격 이상 / 이하               | AAPL이 $200을 돌파할 때 트리거                    |
| 변동률 이상 / 이하             | SPX가 이전 종가 대비 +2% 움직일 때 트리거         |

조건은 결합될 수 있으며(AND 로직), 각 가격 자동화는 **원샷**(한 번 실행) 또는 **반복** 모드를 지원하며, 구성 가능한 쿨다운(최소 4시간 또는 기본적으로 거래일당 한 번)이 있습니다.

> [!NOTE]
> 가격 트리거 자동화는 ginlix-data의 실시간 WebSocket 피드가 필요합니다. 베타 기간 동안 이 기능은 [호스팅 플랫폼](https://ginlix.ai)에서만 독점적으로 사용할 수 있습니다. 더 광범위한 WebSocket 데이터 소스 지원은 향후 릴리스에서 계획되어 있습니다.

<p align="center">
  <img src="https://assets.kitploit.com/production/public/readmes/13458/f30f123382354eda92a4e9fcb5ad3bcd9b446f054807e7243f435101f7dd79fa.png" alt="템플릿 갤러리 및 Mag 7 실적 전 일정이 있는 자동화 페이지" width="800" />
</p>
<p align="center"><em>반복 연구를 예약합니다. — 여기서는 Mag 7 실적 전 분석이 각 보고서보다 앞서 자동으로 실행됩니다.</em></p>

**에이전트 아키텍처**```mermaid
%%{init: {'theme': 'neutral'}}%%

flowchart TB
    subgraph Orchestrator ["BackgroundSubagentOrchestrator"]
        direction TB
        Agent["Main Agent · LangGraph ReAct"]
    end

    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()` 도구를 통해 병렬 비동기 하위 에이전트를 생성합니다. 하위 에이전트는 격리된 컨텍스트 창으로 동시에 실행되어 긴 추론 체인에서의 드리프트를 방지합니다. 각 하위 에이전트는 합성된 결과를 메인 에이전트에 반환하여 오케스트레이터를 가볍게 유지합니다. 메인 에이전트는 하위 에이전트의 결과를 기다리거나 다른 보류 중인 작업을 계속할 수 있습니다. 또한 UI에서 **하위 에이전트** 보기로 전환하여 실시간 진행 상황을 확인할 수 있습니다(웹 프론트엔드 전용).

단순한 디스패치를 넘어, 메인 에이전트는 실행 중인 하위 에이전트에게 후속 지침을 보내거나, 완료된 하위 에이전트를 전체 컨텍스트로 재개하여 반복적인 개선을 수행할 수 있습니다. 서버가 재시작되면 하위 에이전트 상태는 마지막 체크포인트에서 자동으로 재구성됩니다.

<p align="center">
  <img src="https://assets.kitploit.com/production/public/readmes/13458/dd8d54f3a8879372cf72c8a05d6ecce70c53ed0d86c8aed6a49c49276d4f97e4.png" alt="데이터 센터 컴퓨팅 체인을 조사하는 병렬 하위 에이전트와 대화형 AI 컴퓨팅 타임라인" width="800" />
</p>
<p align="center"><em>연구 하위 에이전트가 컴퓨팅 체인 전반에 걸쳐 병렬로 실행됩니다 — 결과는 NVIDIA, Google, AMD, AWS 및 기타 업계를 아우르는 대화형 AI 컴퓨팅 타임라인으로 병합됩니다.</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를 통해 스트리밍합니다: 텍스트 청크, 인수와 결과가 포함된 도구 호출, 하위 에이전트 상태 업데이트, 파일 작업 아티팩트, 인간이 개입하는 인터럽트. 모든 에이전트 결정은 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는 이를 각 턴 옆의 소스 패널로 렌더링합니다: 유형별로 그룹화된 소스, 웹 출처의 파비콘, 제공자, 타임스탬프, 캡처된 인수, 콘텐츠 지문 및 스니펫을 노출하는 상세 보기. *이 턴 / 모든 소스* 토글은 전체 스레드의 전체 데이터 발자국을 표시하며, 파일 또는 메모 소스를 클릭하면 워크스페이스 파일 패널에서 직접 열립니다 — 모든 연구 출력 뒤에 있는 데이터의 완전한 감사 가능한 추적입니다.

## 보안 및 워크스페이스 볼트

LangAlpha는 자격 증명, 코드 실행 및 사용자 제공 비밀 정보 전반에 걸쳐 계층화된 보안 모델을 적용합니다.

**저장 데이터 암호화** — 모든 민감 데이터(BYOK API 키, OAuth 토큰, 볼트 비밀)는 `pgcrypto`를 사용하여 PostgreSQL 내에서 암호화됩니다. 일반 텍스트는 데이터베이스에 저장되지 않습니다.

**자격 증명 유출 탐지** — 모든 도구 출력은 LLM 컨텍스트에 도달하기 전에 스캔됩니다. 미들웨어는 알려진 모든 비밀 값(MCP 서버 키, 샌드박스 토큰, 볼트 비밀)을 확인하고 일치하는 항목을 `[REDACTED:KEY_NAME]`으로 수정합니다. 동일한 수정이 인간이 보는 표면에도 적용됩니다 — 파일 읽기 및 다운로드는 클라이언트에 도달하기 전에 정리됩니다.

**샌드박스 코드 실행** — 각 워크스페이스는 전용 파일 시스템과 네트워크 경계가 있는 자체 [Daytona](https://www.daytona.io/) 클라우드 샌드박스에서 실행됩니다. 보호된 경로 가드는 에이전트가 내부 시스템 디렉터리에 접근하는 것을 방지합니다 — 도구 입력(실행 전 호출 단락)과 도구 출력(유출된 경로 수정)을 모두 차단합니다.

### 워크스페이스 볼트

각 워크스페이스에는 코드 실행 중 에이전트가 사용할 수 있는 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
```
Vault secrets는 암호화된 저장, 모든 에이전트 및 사용자 대상 출력에서의 차단, 직접 파일 접근 차단 등 모든 보호 계층을 상속합니다. 시크릿을 생성, 업데이트, 공개 또는 삭제할 수 있는 사람은 워크스페이스 소유자뿐입니다.

## Frontend

웹 UI는 단순한 채팅 인터페이스를 넘어, 완전한 연구 작업대입니다:

- **구성 가능한 대시보드** — 미리 정의된 레이아웃(모닝 브리프, 트레이더, 리서처, 에이전트 데스크, 트레이더(TradingView), 포트폴리오 스튜어드)으로 시작하거나, 마켓, 인텔리전스, 개인 컨텍스트, 에이전트 표면, 워크스페이스 단축키를 포괄하는 위젯 갤러리에서 직접 구성
- **인라인 금융 차트** — 도구 결과가 대화 스레드 내에 인터랙티브 스파크라인, 막대 차트, 개요 카드로 렌더링
- **인라인 HTML 위젯** — 에이전트가 `ShowWidget` 도구를 통해 인터랙티브 HTML/SVG 시각화(Chart.js 차트, 메트릭 카드, 데이터 테이블)를 대화 내에 직접 렌더링하며, 테마 인식 스타일링과 샌드박싱된 iframe 사용
- **HTML 연구 보고서** — 에이전트가 완전한 독립형 HTML 문서를 `results/`에 작성하며, 실제 브라우저 시맨틱(스크립트 실행, CDN 라이브러리 로드, 상대 에셋 해석)으로 제공되어 전체 화면 보기 및 PDF 내보내기 가능 — 인라인 위젯 및 라이브 대시보드와 구분됨
- **다중 형식 파일 뷰어** — PDF(페이지 매김, 확대/축소), Excel, CSV, HTML 미리보기, 소스 코드(Monaco 편집기, diff 모드) — 다운로드 없이 인라인으로 열람 가능
- **TradingView 차트** — 전체 TradingView 고급 차트(그리기 도구, 지표, 전문 캔들스틱 스타일링 포함)
- **실시간 시장 데이터** — 1초 틱 해상도의 실시간 WebSocket 가격 피드(미국 주식), 장외 시간 시각화, 다중 이동 평균 오버레이
- **에이전트 그려 차트 주석** — 에이전트가 MarketView 차트에 가격 수준, 추세선, 피보나치 되돌림, 이벤트 뱃지를 표시하며, `symbol:timeframe`별로 유지되고 대화 내 인라인 미리보기 제공
- **공유 가능한 대화** — 원클릭 공유(파일 탐색 및 다운로드 접근 권한 세분화), 공개 URL을 통한 재생
- **실시간 하위 에이전트 모니터링** — 각 백그라운드 작업의 스트리밍 출력 및 도구 호출을 실시간으로 관찰하며, 실행 중간 명령 전송 가능
- **출처 증적 패널** — 모든 턴마다 에이전트가 접근한 외부 소스(웹, SEC 제출, 시장 데이터, MCP 도구, 파일)가 파비콘, 콘텐츠 핑거프린트, 스레드별 범위 전환과 함께 나열
- **자동화** — CRUD 관리(cron 빌더, 실행 내역, 수동 트리거, 가격 트리거 자동화 포함) — 주식 또는 지수가 실시간 가격 조건에 도달하면 실행

<p align="center">
  <img src="https://assets.kitploit.com/production/public/readmes/13458/ce010ef17d384f0b0989047d8257ccf2314889610f28b709b74516f6dbde3f08.png" alt="시장 지수 스트립, 시장 뉴스 브리프, 관심 목록이 포함된 대시보드 — 뉴스 브리프가 컨텍스트로 에이전트 채팅에 드롭됨" width="800" />
</p>
<p align="center"><em>대시보드는 시장 지수, 개인 맞춤 브리프, 관심 목록을 표시합니다 — 모든 타일을 에이전트에 채팅 컨텍스트로 고정하여 연구 스레드를 시작할 수 있습니다.</em></p>

<table align="center">
  <tr>
    <td width="50%">
      <img src="https://assets.kitploit.com/production/public/readmes/13458/df356baaa5170b2ee01c7f1ade44b5c72d041c6b6c677165beea5364aa868a37.png" alt="모닝 브리프, 에이전트 데스크, 리서처, 트레이더 템플릿이 포함된 대시보드 프리셋 선택기" />
    </td>
    <td width="50%">
      <img src="https://assets.kitploit.com/production/public/readmes/13458/a3bef617f61ea5230698406f0483677258a4a721d565dc5ff5f5fc0a26b91733.png" alt="마켓, 인텔리전스, 개인, 에이전트, 워크스페이스 카테고리가 포함된 대시보드 위젯 갤러리" />
    </td>
  </tr>
  <tr>
    <td align="center"><em>큐레이트된 프리셋(모닝 브리프, 에이전트 데스크, 리서처, 또는 트레이더)으로 시작하세요.</em></td>
    <td align="center"><em>또는 위젯 갤러리(마켓, 인텔리전스, 개인, 에이전트, 워크스페이스)에서 직접 구성하세요.</em></td>
  </tr>
</table>

## Channel Integrations

이미 사용 중인 도구에서 LangAlpha를 활용하세요. 통합 게이트웨이는 메시징 플랫폼과 코어 에이전트 간 메시지를 중계하며, 각 채널은 네이티브 형식으로 응답을 받습니다. 채널 통합은 원클릭 설정 및 빠른 계정 연결과 함께 호스팅 서비스에서만 독점 제공됩니다. 시작하려면 [integrations](https://ginlix.ai/account/integrations)를 방문하세요.


| 기능                          | Slack | Discord | Feishu | Telegram | WhatsApp |
| ------------------------------ | ----- | ------- | ------ | -------- | -------- |
| 리치 텍스트 / 마크다운           | ✅     | ✅       | ✅      | ✅        | 🔜       |
| 파일 업로드 (사용자 → 에이전트)     | ✅     | ✅       | ✅      | ❌        | ➖        |
| 파일 다운로드 (에이전트 → 사용자)   | ✅     | ✅       | ✅      | ❌        | ➖        |
| 이미지 렌더링                | ✅     | ✅       | ✅      | ❌        | ➖        |
| 인간 개입 인터럽트   | ✅     | ✅       | ✅      | ⚠️       | ➖        |
| 하위 에이전트 추적              | ✅     | ✅       | ✅      | ✅        | 🔜       |
| 워크스페이스 / 모델 선택    | ✅     | ✅       | ✅      | ✅        | 🔜       |
| 자동화 전달 (아웃바운드) | ✅     | ✅       | ❌      | ➖        | ➖        |
| 간소화된 계정 연결     | ✅     | ✅       | ❌      | ❌        | ➖        |
| 슬래시 명령어                 | ✅     | ✅       | ✅      | ✅        | ➖        |


Slack과 Discord는 네이티브 채널 및 스레드 수준 그룹을 제공하며, 이는 LangAlpha 워크스페이스 및 스레드에 자연스럽게 매핑되어 컨텍스트가 네이티브로 관리됩니다. Telegram과 WhatsApp에는 이러한 기본 요소가 없으므로 단순화된 오케스트레이션 모드로 실행됩니다. Feishu는 완전한 메시징 및 카드 기반 UI를 제공하며 OAuth가 곧 제공될 예정입니다. Telegram은 부분 지원을 제공하며 완전한 지원이 곧 제공될 예정입니다. WhatsApp은 계획 단계입니다.

## Getting Started

> [!TIP]
> **직접 호스팅하고 싶지 않으신가요?** [호스팅 버전](https://ginlix.ai)을 사용해 보세요 — 기본적으로 완전한 데이터 인프라(FMP, 실시간 시장 데이터, 클라우드 샌드박스)가 포함되어 있습니다. 자신의 LLM 키(BYOK)를 가져와서 바로 설정 없이 시작할 수 있습니다.

Docker만 있으면 LangAlpha를 시작할 수 있습니다 — 데이터용 API 키, 클라우드 샌드박스가 필요 없습니다. 인프라용 Docker와 AI 모델용 자체 LLM 구독만 있으면 됩니다.```bash
git clone https://github.com/ginlix-ai/langalpha.git
cd langalpha
make config   # interactive wizard — creates .env, configures LLM, data sources, sandbox, and search
make up       # starts PostgreSQL, Redis, backend, and frontend
```
- **프론트엔드:** [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 백엔드로의 OpenTelemetry 트레이스 및 메트릭 (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)를 참조하세요.

## 문서

- **[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