programgarden-core 2.6.2__tar.gz → 2.6.3__tar.gz

{programgarden_core-2.6.2 → programgarden_core-2.6.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: programgarden-core
-Version: 2.6.2
+Version: 2.6.3
 Summary: ProgramGarden Core - 노드 기반 DSL 핵심 타입 정의
 License-Expression: AGPL-3.0-or-later
 Author: 프로그램동산
@@ -60,13 +60,13 @@ poetry add programgarden-core
 
 요구 사항: Python 3.12+
 
-## Node categories (11 categories, 71 core nodes)
+## Node categories (11 categories, 74 core nodes)
 
 | 카테고리 | 노드 수 | 대표 노드 |
 |----------|---------|----------|
 | infra | 8 | StartNode, BrokerNode, ThrottleNode, SplitNode, AggregateNode, IfNode, KoreaStockBrokerNode |
 | account | 13 | AccountNode, OpenOrdersNode, RealAccountNode, RealOrderEventNode (해외주식/선물 + 국내주식) |
-| market | 20 | MarketDataNode, HistoricalDataNode, RealMarketDataNode, WatchlistNode, ExclusionListNode, KoreaStock* |
+| market | 23 | MarketDataNode, HistoricalDataNode, RealMarketDataNode, WatchlistNode, ExclusionListNode, KoreaStockRankingNode, OverseasStockRankingNode, KoreaStock* |
 | condition | 2 | ConditionNode, LogicNode |
 | order | 10 | NewOrderNode, ModifyOrderNode, CancelOrderNode, PositionSizingNode (해외주식/선물 + 국내주식) |
 | risk | 1 | PortfolioNode |
@@ -76,7 +76,7 @@ poetry add programgarden-core
 | analysis | 2 | BacktestEngineNode, BenchmarkCompareNode |
 | ai | 2 | LLMModelNode, AIAgentNode |
 
-> Community adds two nodes: TelegramNode and PerformanceReportNode, for 73 total.
+> Community adds two nodes: TelegramNode and PerformanceReportNode, for 76 total.
 
 ## 사용 예시
 

{programgarden_core-2.6.2 → programgarden_core-2.6.3}/README.md

@@ -43,13 +43,13 @@ poetry add programgarden-core
 
 요구 사항: Python 3.12+
 
-## Node categories (11 categories, 71 core nodes)
+## Node categories (11 categories, 74 core nodes)
 
 | 카테고리 | 노드 수 | 대표 노드 |
 |----------|---------|----------|
 | infra | 8 | StartNode, BrokerNode, ThrottleNode, SplitNode, AggregateNode, IfNode, KoreaStockBrokerNode |
 | account | 13 | AccountNode, OpenOrdersNode, RealAccountNode, RealOrderEventNode (해외주식/선물 + 국내주식) |
-| market | 20 | MarketDataNode, HistoricalDataNode, RealMarketDataNode, WatchlistNode, ExclusionListNode, KoreaStock* |
+| market | 23 | MarketDataNode, HistoricalDataNode, RealMarketDataNode, WatchlistNode, ExclusionListNode, KoreaStockRankingNode, OverseasStockRankingNode, KoreaStock* |
 | condition | 2 | ConditionNode, LogicNode |
 | order | 10 | NewOrderNode, ModifyOrderNode, CancelOrderNode, PositionSizingNode (해외주식/선물 + 국내주식) |
 | risk | 1 | PortfolioNode |
@@ -59,7 +59,7 @@ poetry add programgarden-core
 | analysis | 2 | BacktestEngineNode, BenchmarkCompareNode |
 | ai | 2 | LLMModelNode, AIAgentNode |
 
-> Community adds two nodes: TelegramNode and PerformanceReportNode, for 73 total.
+> Community adds two nodes: TelegramNode and PerformanceReportNode, for 76 total.
 
 ## 사용 예시
 

{programgarden_core-2.6.2 → programgarden_core-2.6.3}/programgarden_core/__init__.py

@@ -51,6 +51,7 @@ __all__ = [
     "OverseasStockHistoricalDataNode",
     "OverseasStockRealMarketDataNode",
     "OverseasStockSymbolQueryNode",
+    "OverseasStockRankingNode",
     # Nodes - Market (해외선물)
     "OverseasFuturesMarketDataNode",
     "OverseasFuturesHistoricalDataNode",
@@ -63,6 +64,7 @@ __all__ = [
     "KoreaStockHistoricalDataNode",
     "KoreaStockRealMarketDataNode",
     "KoreaStockSymbolQueryNode",
+    "KoreaStockRankingNode",
     "KoreaStockFundamentalNode",
     # Nodes - Account (해외주식)
     "OverseasStockAccountNode",

{programgarden_core-2.6.2 → programgarden_core-2.6.3}/programgarden_core/i18n/locales/en.json

@@ -94,6 +94,10 @@
   "nodes.KoreaStockRealOrderEventNode.name": "Korea Stock Real Order Event",
   "nodes.KoreaStockSymbolQueryNode.description": "Queries all tradable symbols on KOSPI/KOSDAQ markets. Uses t9945 API to fetch symbol names and codes. Filter by market type (All, KOSPI, KOSDAQ). Outputs symbol list and count. Requires an upstream KoreaStockBrokerNode. Typical connection: KoreaStockSymbolQueryNode → ConditionNode or → KoreaStockMarketDataNode.",
   "nodes.KoreaStockSymbolQueryNode.name": "Korea Stock Symbols",
+  "nodes.KoreaStockRankingNode.description": "Lists today's top domestic stocks by gain, loss, volume, trading value or market cap (LS t1441, t1452, t1463, t1444). Outputs ranked rows, a KoreaStock symbol list and the count. Read-only, real account only. Requires an upstream KoreaStockBrokerNode. Typical connection: KoreaStockRankingNode → CodeNode (pick) → KoreaStockMarketDataNode.",
+  "nodes.KoreaStockRankingNode.name": "Korea Stock Ranking",
+  "nodes.OverseasStockRankingNode.description": "Lists today's top US stocks by gain, loss, volume, trading value, turnover, market cap or 52-week high/low (LS g3112). Outputs ranked rows, an overseas-stock symbol list and the count. Read-only. Requires an upstream OverseasStockBrokerNode. Typical connection: OverseasStockRankingNode → CodeNode (pick) → OverseasStockMarketDataNode.",
+  "nodes.OverseasStockRankingNode.name": "Overseas Stock Ranking",
   "nodes.LineChartNode.description": "Renders a time-series line chart on the workflow canvas. Configure x-axis field (typically date) and y-axis field (price, equity, etc.), with optional signal and side markers for buy/sell visualization. Bind data from HistoricalDataNode, BacktestEngineNode equity curves, or any time-series output. Outputs a 'rendered' signal when display is complete. Typical connection: BacktestEngineNode.equity_curve → LineChartNode.",
   "nodes.LineChartNode.name": "Line Chart",
   "nodes.LLMModelNode.description": "Provides LLM (Large Language Model) API connection for AI Agent nodes. Acts as the authentication gateway for LLM services — similar to BrokerNode pattern. Supports OpenAI, Anthropic, and Google credentials. Configure model ID (e.g., gpt-4o, claude-sonnet-4-5-20250929), temperature, max tokens, seed for reproducibility, and streaming mode. Connect to AIAgentNode via ai_model edge type. Does not execute independently — only provides the connection. Typical connection: LLMModelNode →(ai_model edge)→ AIAgentNode.",
@@ -345,6 +349,12 @@
   "fields.KoreaStockRealOrderEventNode.event_filter": "Select which Korea stock order notifications to receive. Choose 'All' to get all order events.",
   "fields.KoreaStockRealOrderEventNode.stay_connected": "✅ ON: Continuously receives order fill/reject/cancel notifications.\n❌ OFF: Receives events once and disconnects.",
   "fields.KoreaStockSymbolQueryNode.market": "Select the market to query. Choose All, KOSPI, or KOSDAQ.",
+  "fields.KoreaStockRankingNode.ranking_type": "Choose what to rank by: top gainers, top losers, volume, trading value or market cap.",
+  "fields.KoreaStockRankingNode.market": "Choose All, KOSPI or KOSDAQ. Market cap ranking needs KOSPI or KOSDAQ.",
+  "fields.KoreaStockRankingNode.limit": "Maximum number of ranked stocks to return (1-100).",
+  "fields.OverseasStockRankingNode.ranking_type": "Choose what to rank by: top gainers, top losers, volume, trading value, turnover, market cap, 52-week high or 52-week low.",
+  "fields.OverseasStockRankingNode.market": "Choose the US segment: All, NYSE, NASDAQ or ETF.",
+  "fields.OverseasStockRankingNode.limit": "Maximum number of ranked stocks to return (1-100).",
   "fields.LLMModelNode.credential_id": "LLM API Credential",
   "fields.LLMModelNode.model": "Model",
   "fields.LLMModelNode.model_help": "LLM model ID to use. e.g. gpt-4o, claude-sonnet-4-5-20250929, llama3.1",
@@ -638,6 +648,12 @@
   "fieldNames.KoreaStockRealOrderEventNode.event_filter": "Event Filter",
   "fieldNames.KoreaStockRealOrderEventNode.stay_connected": "Stay Connected",
   "fieldNames.KoreaStockSymbolQueryNode.market": "Market",
+  "fieldNames.KoreaStockRankingNode.ranking_type": "Ranking",
+  "fieldNames.KoreaStockRankingNode.market": "Market",
+  "fieldNames.KoreaStockRankingNode.limit": "Count",
+  "fieldNames.OverseasStockRankingNode.ranking_type": "Ranking",
+  "fieldNames.OverseasStockRankingNode.market": "Market",
+  "fieldNames.OverseasStockRankingNode.limit": "Count",
   "fieldNames.LineChartNode.data": "Data",
   "fieldNames.LineChartNode.side_field": "Side Field",
   "fieldNames.LineChartNode.signal_field": "Signal Field",
@@ -956,6 +972,7 @@
   "ports.summary": "Performance summary",
   "ports.symbol": "Symbol code",
   "ports.symbols": "List of symbols",
+  "ports.rankings": "Ranked rows",
   "ports.target_orders": "Target orders",
   "ports.throttle_stats": "Throttle stats (skip count, countdown, etc.)",
   "ports.tick_data": "Tick data",
@@ -1027,6 +1044,18 @@
   "enums.kr_market.KOSDAQ": "KOSDAQ",
   "enums.kr_market.KOSPI": "KOSPI",
   "enums.kr_market.all": "All",
+  "enums.ranking_type.change_rate_up": "Top gainers",
+  "enums.ranking_type.change_rate_down": "Top losers",
+  "enums.ranking_type.volume": "Volume",
+  "enums.ranking_type.trading_value": "Trading value",
+  "enums.ranking_type.turnover": "Turnover",
+  "enums.ranking_type.market_cap": "Market cap",
+  "enums.ranking_type.high_52w": "52-week high",
+  "enums.ranking_type.low_52w": "52-week low",
+  "enums.us_ranking_market.all": "All",
+  "enums.us_ranking_market.NYSE": "NYSE",
+  "enums.us_ranking_market.NASDAQ": "NASDAQ",
+  "enums.us_ranking_market.ETF": "ETF",
   "enums.kr_price_type.conditional_limit": "Conditional Limit",
   "enums.kr_price_type.limit": "Limit",
   "enums.kr_price_type.market": "Market",

{programgarden_core-2.6.2 → programgarden_core-2.6.3}/programgarden_core/i18n/locales/ko.json

@@ -94,6 +94,10 @@
   "nodes.KoreaStockRealOrderEventNode.name": "국내주식 실시간 주문 이벤트",
   "nodes.KoreaStockSymbolQueryNode.description": "KOSPI/KOSDAQ 전체 거래 가능 종목을 조회합니다. t9945 API로 종목명, 종목코드를 가져옵니다. 시장 구분(전체, KOSPI, KOSDAQ)으로 필터링 가능. 출력: 종목 목록, 종목 수. 상위 KoreaStockBrokerNode 연결 필수. 일반적인 연결: KoreaStockSymbolQueryNode → ConditionNode 또는 → KoreaStockMarketDataNode.",
   "nodes.KoreaStockSymbolQueryNode.name": "국내주식 종목 조회",
+  "nodes.KoreaStockRankingNode.description": "오늘의 국내주식 상위 종목을 등락률(상승·하락), 거래량, 거래대금, 시가총액 기준으로 조회합니다 (LS t1441, t1452, t1463, t1444). 출력: 순위 행, 국내주식 종목 리스트, 종목 수. 읽기 전용이며 실계좌 전용입니다. 상위 KoreaStockBrokerNode 연결 필수. 일반적인 연결: KoreaStockRankingNode → CodeNode(선별) → KoreaStockMarketDataNode.",
+  "nodes.KoreaStockRankingNode.name": "국내주식 순위",
+  "nodes.OverseasStockRankingNode.description": "오늘의 미국 주식 상위 종목을 등락률(상승·하락), 거래량, 거래대금, 회전율, 시가총액, 52주 신고가·신저가 기준으로 조회합니다 (LS g3112). 출력: 순위 행, 해외주식 종목 리스트, 종목 수. 읽기 전용입니다. 상위 OverseasStockBrokerNode 연결 필수. 일반적인 연결: OverseasStockRankingNode → CodeNode(선별) → OverseasStockMarketDataNode.",
+  "nodes.OverseasStockRankingNode.name": "해외주식 순위",
   "nodes.LineChartNode.description": "워크플로우 캔버스에 시계열 라인 차트를 렌더링합니다. X축 필드(보통 날짜)와 Y축 필드(가격, 자산 등)를 설정하고, 매수/매도 시각화를 위한 signal/side 마커를 선택적으로 추가합니다. HistoricalDataNode, BacktestEngineNode equity curve 등 시계열 데이터를 바인딩합니다. 표시 완료 시 'rendered' 신호 출력. 일반적인 연결: BacktestEngineNode.equity_curve → LineChartNode.",
   "nodes.LineChartNode.name": "라인차트",
   "nodes.LLMModelNode.description": "AI Agent 노드에 LLM(대규모 언어 모델) API 연결을 제공합니다. BrokerNode와 유사한 인증 게이트웨이 패턴입니다. OpenAI, Anthropic, Google 인증 지원. 모델 ID(예: gpt-4o, claude-sonnet-4-5-20250929), temperature, max tokens, 재현성을 위한 seed, 스트리밍 모드를 설정합니다. ai_model 엣지로 AIAgentNode에 연결합니다. 독립 실행 불가 — 연결만 제공합니다. 일반적인 연결: LLMModelNode →(ai_model 엣지)→ AIAgentNode.",
@@ -345,6 +349,12 @@
   "fields.KoreaStockRealOrderEventNode.event_filter": "받고 싶은 국내주식 주문 알림을 선택하세요. '전체'를 선택하면 모든 주문 이벤트를 받습니다.",
   "fields.KoreaStockRealOrderEventNode.stay_connected": "✅ 켜면: 주문 체결/거부/취소 알림을 계속 받습니다.\n❌ 끄면: 이벤트를 한 번만 받고 끊깁니다.",
   "fields.KoreaStockSymbolQueryNode.market": "조회할 시장을 선택하세요. 전체, KOSPI(유가증권), KOSDAQ(코스닥) 중 선택합니다.",
+  "fields.KoreaStockRankingNode.ranking_type": "순위 기준을 고르세요. 상승률, 하락률, 거래량, 거래대금, 시가총액 중 선택합니다.",
+  "fields.KoreaStockRankingNode.market": "전체, KOSPI(유가증권), KOSDAQ(코스닥) 중 선택합니다. 시가총액 순위는 KOSPI 또는 KOSDAQ 을 골라야 합니다.",
+  "fields.KoreaStockRankingNode.limit": "가져올 순위 종목 수의 최대값입니다 (1~100).",
+  "fields.OverseasStockRankingNode.ranking_type": "순위 기준을 고르세요. 상승률, 하락률, 거래량, 거래대금, 회전율, 시가총액, 52주 신고가, 52주 신저가 중 선택합니다.",
+  "fields.OverseasStockRankingNode.market": "미국 시장 구분을 고르세요. 전체, 뉴욕(NYSE), 나스닥(NASDAQ), ETF 중 선택합니다.",
+  "fields.OverseasStockRankingNode.limit": "가져올 순위 종목 수의 최대값입니다 (1~100).",
   "fields.LLMModelNode.credential_id": "LLM API 인증정보",
   "fields.LLMModelNode.model": "모델",
   "fields.LLMModelNode.model_help": "사용할 LLM 모델 ID입니다. 예: gpt-4o, claude-sonnet-4-5-20250929, llama3.1",
@@ -638,6 +648,12 @@
   "fieldNames.KoreaStockRealOrderEventNode.event_filter": "이벤트필터",
   "fieldNames.KoreaStockRealOrderEventNode.stay_connected": "연결유지",
   "fieldNames.KoreaStockSymbolQueryNode.market": "시장구분",
+  "fieldNames.KoreaStockRankingNode.ranking_type": "순위 기준",
+  "fieldNames.KoreaStockRankingNode.market": "시장구분",
+  "fieldNames.KoreaStockRankingNode.limit": "종목 수",
+  "fieldNames.OverseasStockRankingNode.ranking_type": "순위 기준",
+  "fieldNames.OverseasStockRankingNode.market": "시장구분",
+  "fieldNames.OverseasStockRankingNode.limit": "종목 수",
   "fieldNames.LineChartNode.data": "데이터",
   "fieldNames.LineChartNode.side_field": "방향필드",
   "fieldNames.LineChartNode.signal_field": "시그널필드",
@@ -956,6 +972,7 @@
   "ports.summary": "성과 요약",
   "ports.symbol": "종목 코드",
   "ports.symbols": "종목 리스트",
+  "ports.rankings": "순위 목록",
   "ports.target_orders": "대상 주문",
   "ports.throttle_stats": "쓰로틀 통계 (스킵 횟수, 카운트다운 등)",
   "ports.tick_data": "틱 데이터",
@@ -1027,6 +1044,18 @@
   "enums.kr_market.KOSDAQ": "KOSDAQ (코스닥)",
   "enums.kr_market.KOSPI": "KOSPI (유가증권)",
   "enums.kr_market.all": "전체",
+  "enums.ranking_type.change_rate_up": "상승률 상위",
+  "enums.ranking_type.change_rate_down": "하락률 상위",
+  "enums.ranking_type.volume": "거래량 상위",
+  "enums.ranking_type.trading_value": "거래대금 상위",
+  "enums.ranking_type.turnover": "회전율 상위",
+  "enums.ranking_type.market_cap": "시가총액 상위",
+  "enums.ranking_type.high_52w": "52주 신고가",
+  "enums.ranking_type.low_52w": "52주 신저가",
+  "enums.us_ranking_market.all": "전체",
+  "enums.us_ranking_market.NYSE": "뉴욕(NYSE)",
+  "enums.us_ranking_market.NASDAQ": "나스닥(NASDAQ)",
+  "enums.us_ranking_market.ETF": "ETF",
   "enums.kr_price_type.conditional_limit": "조건부지정가 (Conditional Limit)",
   "enums.kr_price_type.limit": "지정가 (Limit)",
   "enums.kr_price_type.market": "시장가 (Market)",

{programgarden_core-2.6.2 → programgarden_core-2.6.3}/programgarden_core/nodes/__init__.py

@@ -100,6 +100,8 @@ from programgarden_core.nodes.data_korea_stock import KoreaStockMarketDataNode
 from programgarden_core.nodes.fundamental_korea_stock import KoreaStockFundamentalNode
 from programgarden_core.nodes.backtest_korea_stock import KoreaStockHistoricalDataNode
 from programgarden_core.nodes.symbol_korea_stock import KoreaStockSymbolQueryNode
+from programgarden_core.nodes.ranking_korea_stock import KoreaStockRankingNode
+from programgarden_core.nodes.ranking_stock import OverseasStockRankingNode
 from programgarden_core.nodes.realtime_korea_stock import (
     KoreaStockRealMarketDataNode,
     KoreaStockRealAccountNode,
@@ -196,6 +198,8 @@ __all__ = [
     "KoreaStockHistoricalDataNode",
     "KoreaStockRealMarketDataNode",
     "KoreaStockSymbolQueryNode",
+    "KoreaStockRankingNode",
+    "OverseasStockRankingNode",
     # Account - Korea Stock (국내주식)
     "KoreaStockAccountNode",
     "KoreaStockOpenOrdersNode",

{programgarden_core-2.6.2 → programgarden_core-2.6.3}/programgarden_core/nodes/base.py

@@ -185,6 +185,72 @@ KOREA_STOCK_SYMBOL_QUERY_FIELDS: List[Dict[str, str]] = [
     {"name": "product", "type": "string", "description": "상품 구분 (항상 korea_stock)"},
 ]
 
+# ── KoreaStockRankingNode.rankings (t1441 / t1452 / t1463 / t1444) ──
+# Values are consumed as returned by LS; units are named, never converted.
+KOREA_STOCK_RANKING_FIELDS: List[Dict[str, str]] = [
+    {"name": "rank", "type": "integer", "description": "1-based rank in this result"},
+    {"name": "symbol", "type": "string", "description": "6-digit KRX code (shcode)"},
+    {"name": "exchange", "type": "string", "description": "Always KRX"},
+    {"name": "market", "type": "string", "description": "KOSPI/KOSDAQ when the request named a market; null for market=all"},
+    {"name": "name", "type": "string", "description": "Issue name (hname)"},
+    {"name": "price", "type": "number", "description": "Current price"},
+    {"name": "open", "type": "number", "description": "Session open (t1441 only; null otherwise)"},
+    {"name": "high", "type": "number", "description": "Session high (t1441 only; null otherwise)"},
+    {"name": "low", "type": "number", "description": "Session low (t1441 only; null otherwise)"},
+    {"name": "sign", "type": "string", "description": "Raw LS direction code (1 upper limit, 2 up, 3 unchanged, 4 lower limit, 5 down)"},
+    {"name": "change", "type": "number", "description": "Change vs previous close, signed from the sign code"},
+    {"name": "change_pct", "type": "number", "description": "Change percent vs previous close, signed from the sign code"},
+    {"name": "volume", "type": "number", "description": "Cumulative volume (shares)"},
+    {"name": "trading_value", "type": "number", "description": "Trading value as returned (t1441/t1463; null otherwise)"},
+    {"name": "trading_value_unit", "type": "string", "description": "as_returned (t1441) or KRW_million (t1463); null when trading_value is null"},
+    {"name": "market_cap", "type": "number", "description": "Market capitalisation as returned (t1441/t1463/t1444; null for t1452)"},
+    {"name": "market_cap_unit", "type": "string", "description": "as_returned (t1441), KRW_million (t1463) or KRW_100million (t1444); null when market_cap is null"},
+    {"name": "product", "type": "string", "description": "Always korea_stock"},
+    {"name": "source_tr", "type": "string", "description": "LS TR that produced the row (t1441/t1452/t1463/t1444)"},
+]
+
+# ── KoreaStockRankingNode.symbols ──
+KOREA_STOCK_RANKING_SYMBOL_FIELDS: List[Dict[str, str]] = [
+    {"name": "exchange", "type": "string", "description": "Always KRX"},
+    {"name": "market", "type": "string", "description": "KOSPI/KOSDAQ when the request named a market; null for market=all"},
+    {"name": "symbol", "type": "string", "description": "6-digit KRX code"},
+    {"name": "name", "type": "string", "description": "Issue name"},
+    {"name": "product", "type": "string", "description": "Always korea_stock"},
+]
+
+# ── OverseasStockRankingNode.rankings (g3112) ──
+OVERSEAS_STOCK_RANKING_FIELDS: List[Dict[str, str]] = [
+    {"name": "rank", "type": "integer", "description": "1-based rank in this result"},
+    {"name": "symbol", "type": "string", "description": "Ticker symbol"},
+    {"name": "exchange", "type": "string", "description": "NYSE or NASDAQ from the LS key symbol prefix (81/82); null when unavailable"},
+    {"name": "exchange_source", "type": "string", "description": "keysymbol when derived from the LS key symbol, otherwise unavailable"},
+    {"name": "name", "type": "string", "description": "Korean issue name (korname)"},
+    {"name": "exchange_name", "type": "string", "description": "LS exchange label and symbol as returned (exsymbol, e.g. '나스닥 AEHL')"},
+    {"name": "keysymbol", "type": "string", "description": "LS key symbol as returned"},
+    {"name": "price", "type": "number", "description": "Current price"},
+    {"name": "sign", "type": "string", "description": "Raw LS direction code"},
+    {"name": "change", "type": "number", "description": "Change vs previous close, signed from the sign code"},
+    {"name": "change_pct", "type": "number", "description": "Change percent vs previous close, signed from the sign code"},
+    {"name": "volume", "type": "number", "description": "Volume"},
+    {"name": "trading_value", "type": "number", "description": "Trading value as returned by LS (unit not declared)"},
+    {"name": "trading_value_unit", "type": "string", "description": "as_returned; null when trading_value is null"},
+    {"name": "turnover", "type": "number", "description": "Turnover as returned by LS"},
+    {"name": "market_cap", "type": "number", "description": "Market capitalisation as returned by LS (unit not declared)"},
+    {"name": "market_cap_unit", "type": "string", "description": "as_returned; null when market_cap is null"},
+    {"name": "high_52w", "type": "number", "description": "52-week high"},
+    {"name": "low_52w", "type": "number", "description": "52-week low"},
+    {"name": "product", "type": "string", "description": "Always overseas_stock"},
+    {"name": "source_tr", "type": "string", "description": "Always g3112"},
+]
+
+# ── OverseasStockRankingNode.symbols ── (rows without a known exchange are omitted)
+OVERSEAS_STOCK_RANKING_SYMBOL_FIELDS: List[Dict[str, str]] = [
+    {"name": "exchange", "type": "string", "description": "NYSE or NASDAQ"},
+    {"name": "symbol", "type": "string", "description": "Ticker symbol"},
+    {"name": "name", "type": "string", "description": "Korean issue name"},
+    {"name": "product", "type": "string", "description": "Always overseas_stock"},
+]
+
 # ── OverseasFuturesSymbolQueryNode.symbols (o3101 마스터) ──
 OVERSEAS_FUTURES_SYMBOL_QUERY_FIELDS: List[Dict[str, str]] = [
     {"name": "exchange", "type": "string", "description": "거래소 코드 (CME, HKEX 등 — 주문에 쓰는 값)"},

programgarden_core-2.6.3/programgarden_core/nodes/ranking_korea_stock.py

@@ -0,0 +1,277 @@
+"""
+ProgramGarden Core - Korea Stock Ranking Node
+
+국내주식 순위 조회:
+- KoreaStockRankingNode: 등락률·거래량·거래대금·시가총액 상위 종목 (LS t1441 / t1452 / t1463 / t1444)
+"""
+
+from typing import Any, ClassVar, Dict, List, Literal, Optional, TYPE_CHECKING
+
+from pydantic import Field
+
+if TYPE_CHECKING:
+    from programgarden_core.models.field_binding import FieldSchema
+
+from programgarden_core.nodes.base import (
+    BaseNode,
+    BrokerProvider,
+    InputPort,
+    KOREA_STOCK_RANKING_FIELDS,
+    KOREA_STOCK_RANKING_SYMBOL_FIELDS,
+    NodeCategory,
+    OutputPort,
+    ProductScope,
+)
+
+
+KOREA_RANKING_TYPES = ["change_rate_up", "change_rate_down", "volume", "trading_value", "market_cap"]
+KOREA_RANKING_MARKETS = ["all", "KOSPI", "KOSDAQ"]
+RANKING_LIMIT_MIN = 1
+RANKING_LIMIT_MAX = 100
+
+# The programgarden engine runs both ranking nodes with its own executor from this
+# version. An older engine paired with this core falls back to its generic executor,
+# which calls the node's ``execute``; without the method below it would report the
+# node as executed with no rankings and no error.
+RANKING_MIN_ENGINE = "2.6.6"
+
+
+def ranking_engine_required(node_type: str) -> RuntimeError:
+    """Error raised when an engine without the ranking executor runs a ranking node."""
+    return RuntimeError(
+        f"{node_type} requires the programgarden engine {RANKING_MIN_ENGINE} or later; "
+        "this engine has no ranking executor, so no ranking was read. "
+        "Update the programgarden package (updating programgarden-core alone is not enough)."
+    )
+
+
+_BROKER_CREDENTIAL = {
+    "credential_id": "broker_cred",
+    "type": "broker_ls_korea_stock",
+    "data": [
+        {"key": "appkey", "value": "", "type": "password", "label": "App Key"},
+        {"key": "appsecret", "value": "", "type": "password", "label": "App Secret"},
+    ],
+}
+
+
+class KoreaStockRankingNode(BaseNode):
+    """
+    국내주식 순위 노드
+
+    KOSPI/KOSDAQ 의 등락률·거래량·거래대금·시가총액 상위 종목을 조회합니다.
+    LS t1441(등락율상위) / t1452(거래량상위) / t1463(거래대금상위) / t1444(시가총액상위).
+    읽기 전용 노드이며 주문을 내지 않습니다.
+    """
+
+    type: Literal["KoreaStockRankingNode"] = "KoreaStockRankingNode"
+    category: NodeCategory = NodeCategory.MARKET
+    description: str = "i18n:nodes.KoreaStockRankingNode.description"
+    _img_url: ClassVar[str] = ""
+    _product_scope: ClassVar[ProductScope] = ProductScope.KOREA_STOCK
+    _broker_provider: ClassVar[BrokerProvider] = BrokerProvider.LS
+
+    ranking_type: str = Field(
+        default="change_rate_up",
+        description="Ranking: change_rate_up, change_rate_down, volume, trading_value, market_cap",
+    )
+    market: str = Field(
+        default="all",
+        description="Market: all, KOSPI, KOSDAQ (market_cap needs KOSPI or KOSDAQ)",
+    )
+    limit: int = Field(
+        default=20,
+        ge=RANKING_LIMIT_MIN,
+        le=RANKING_LIMIT_MAX,
+        description="Maximum number of ranked rows (1-100)",
+    )
+
+    _usage: ClassVar[Dict[str, Any]] = {
+        "when_to_use": [
+            "Pick today's top domestic gainers, losers, most traded or largest stocks as a candidate list",
+            "Start an intraday screen from the whole KOSPI/KOSDAQ market instead of a fixed watchlist",
+        ],
+        "when_not_to_use": [
+            "For the full listed universe — use KoreaStockSymbolQueryNode",
+            "For overseas stocks — use OverseasStockRankingNode",
+            "For a fixed list of symbols — use WatchlistNode",
+        ],
+        "typical_scenarios": [
+            "KoreaStockRankingNode(change_rate_up) → CodeNode (filter and pick) → KoreaStockMarketDataNode → order decision",
+            "KoreaStockRankingNode(trading_value) → TableDisplayNode (market overview)",
+            "KoreaStockRankingNode.symbols → SplitNode → KoreaStockHistoricalDataNode (per-symbol history)",
+        ],
+    }
+    _features: ClassVar[List[str]] = [
+        "One node, four LS ranking TRs: change_rate_up/change_rate_down → t1441, volume → t1452, trading_value → t1463, market_cap → t1444",
+        "Outputs `rankings` (full rows), `symbols` (KoreaStock symbol list) and `count`",
+        "Change and change percent are signed from the LS sign code; units are named (trading_value_unit, market_cap_unit) and never converted",
+        "Pages with the LS cursor up to `limit` rows, at most 5 requests per run, at the SDK rate limit of each TR",
+        "Read-only and real-account only — KoreaStock has no paper trading; no order is ever placed",
+        "Deep validation and dry runs return 3 synthetic rows with the same shape and make no broker call",
+    ]
+    _anti_patterns: ClassVar[List[Dict[str, str]]] = [
+        {
+            "pattern": "Wiring `symbols` or `rankings` straight into KoreaStockNewOrderNode",
+            "reason": "A ranking is a moving market snapshot, not a trading decision. Top gainers often include limit-up, halted-adjacent or illiquid issues.",
+            "alternative": "Filter in a CodeNode or ConditionNode (price, change range, holdings, open orders, budget) and order at most the chosen symbol.",
+        },
+        {
+            "pattern": "Adding the five TRs together or comparing trading_value across ranking types",
+            "reason": "Each TR reports in its own unit (as_returned, KRW_million, KRW_100million).",
+            "alternative": "Read trading_value_unit / market_cap_unit before comparing values.",
+        },
+        {
+            "pattern": "Using market_cap with market='all'",
+            "reason": "t1444 ranks one market index at a time (001 KOSPI, 301 KOSDAQ).",
+            "alternative": "Choose market='KOSPI' or market='KOSDAQ', or use two nodes.",
+        },
+    ]
+    _examples: ClassVar[List[Dict[str, Any]]] = [
+        {
+            "title": "Top 30 domestic gainers",
+            "description": "List today's 30 biggest gainers across KOSPI and KOSDAQ.",
+            "workflow_snippet": {
+                "id": "korea_stock_ranking_gainers",
+                "name": "Domestic Top Gainers",
+                "nodes": [
+                    {"id": "start", "type": "StartNode"},
+                    {"id": "broker", "type": "KoreaStockBrokerNode", "credential_id": "broker_cred"},
+                    {"id": "ranking", "type": "KoreaStockRankingNode", "ranking_type": "change_rate_up", "market": "all", "limit": 30},
+                    {"id": "display", "type": "TableDisplayNode", "data": "{{ nodes.ranking.rankings }}"},
+                ],
+                "edges": [
+                    {"from": "start", "to": "broker"},
+                    {"from": "broker", "to": "ranking"},
+                    {"from": "ranking", "to": "display"},
+                ],
+                "credentials": [_BROKER_CREDENTIAL],
+            },
+            "expected_output": "rankings: [{rank, symbol, name, price, change_pct, volume, ...}] (30 rows); count: 30.",
+        },
+        {
+            "title": "KOSPI market-cap leaders into a screen",
+            "description": "Take the 20 largest KOSPI issues and pass the symbol list to a CodeNode for screening.",
+            "workflow_snippet": {
+                "id": "korea_stock_ranking_market_cap",
+                "name": "KOSPI Market Cap Leaders",
+                "nodes": [
+                    {"id": "start", "type": "StartNode"},
+                    {"id": "broker", "type": "KoreaStockBrokerNode", "credential_id": "broker_cred"},
+                    {"id": "ranking", "type": "KoreaStockRankingNode", "ranking_type": "market_cap", "market": "KOSPI", "limit": 20},
+                    {
+                        "id": "screen",
+                        "type": "CodeNode",
+                        "data": "{{ nodes.ranking.rankings }}",
+                        "code": (
+                            "async def execute(data, params, context):\n"
+                            "    rows = [r for r in (data or []) if (r.get('change_pct') or 0) > 0]\n"
+                            "    return {'picked': rows[:5]}"
+                        ),
+                        "outputs": [{"name": "picked", "type": "array"}],
+                    },
+                ],
+                "edges": [
+                    {"from": "start", "to": "broker"},
+                    {"from": "broker", "to": "ranking"},
+                    {"from": "ranking", "to": "screen"},
+                ],
+                "credentials": [_BROKER_CREDENTIAL],
+            },
+            "expected_output": "screen.picked: up to 5 KOSPI market-cap leaders that are up today.",
+        },
+    ]
+    _node_guide: ClassVar[Dict[str, Any]] = {
+        "input_handling": (
+            "No symbol input. Choose ranking_type (change_rate_up, change_rate_down, volume, trading_value, market_cap), "
+            "market (all, KOSPI, KOSDAQ; market_cap needs KOSPI or KOSDAQ) and limit (1-100). "
+            "A connected KoreaStockBrokerNode supplies the real-account connection automatically."
+        ),
+        "output_consumption": (
+            "`rankings` rows: rank, symbol (6 digits), exchange (KRX), market (KOSPI/KOSDAQ or null for all), name, price, "
+            "open/high/low (t1441 only, else null), sign (raw code), change and change_pct (signed), volume, "
+            "trading_value + trading_value_unit, market_cap + market_cap_unit, product (korea_stock), source_tr. "
+            "`symbols` items: {exchange, market, symbol, name, product} — the KoreaStock symbol-list shape. "
+            "`count`: number of rows. An empty successful result is valid (rankings=[], count=0). "
+            "Deep validation and dry runs emit 3 synthetic rows (005930, 000660, 035420) with this exact shape and no broker call."
+        ),
+        "common_combinations": [
+            "KoreaStockRankingNode.rankings → CodeNode (decision) → KoreaStockNewOrderNode",
+            "KoreaStockRankingNode.symbols → SplitNode → KoreaStockMarketDataNode",
+            "KoreaStockRankingNode.rankings → TableDisplayNode",
+        ],
+        "pitfalls": [
+            "Rankings move every second; re-check price and holdings right before ordering",
+            "Units differ by ranking type — read trading_value_unit / market_cap_unit",
+            "LS failures raise with the TR code first (e.g. 't1441: <code> <message>'); missing credentials fail the node",
+            "KoreaStock is real-account only",
+        ],
+    }
+
+    _inputs: List[InputPort] = []
+    _outputs: List[OutputPort] = [
+        OutputPort(name="rankings", type="array", description="i18n:ports.rankings", fields=KOREA_STOCK_RANKING_FIELDS),
+        OutputPort(name="symbols", type="symbol_list", description="i18n:ports.symbols", fields=KOREA_STOCK_RANKING_SYMBOL_FIELDS),
+        OutputPort(name="count", type="integer", description="i18n:ports.count"),
+    ]
+
+    _version: ClassVar[str] = "1.0.0"
+    _updated_at: ClassVar[str] = "2026-10-15"
+    _change_note: ClassVar[Optional[str]] = "New: domestic gainers/losers/volume/trading value/market cap rankings (LS)."
+
+    @classmethod
+    def get_field_schema(cls) -> Dict[str, "FieldSchema"]:
+        from programgarden_core.models.field_binding import ExpressionMode, FieldCategory, FieldSchema, FieldType
+        return {
+            "ranking_type": FieldSchema(
+                name="ranking_type",
+                type=FieldType.ENUM,
+                description="i18n:fields.KoreaStockRankingNode.ranking_type",
+                default="change_rate_up",
+                enum_values=list(KOREA_RANKING_TYPES),
+                enum_labels={value: f"i18n:enums.ranking_type.{value}" for value in KOREA_RANKING_TYPES},
+                required=False,
+                category=FieldCategory.PARAMETERS,
+                expression_mode=ExpressionMode.FIXED_ONLY,
+                example="change_rate_up",
+                expected_type="str",
+            ),
+            "market": FieldSchema(
+                name="market",
+                type=FieldType.ENUM,
+                description="i18n:fields.KoreaStockRankingNode.market",
+                default="all",
+                enum_values=list(KOREA_RANKING_MARKETS),
+                enum_labels={
+                    "all": "i18n:enums.kr_market.all",
+                    "KOSPI": "i18n:enums.kr_market.KOSPI",
+                    "KOSDAQ": "i18n:enums.kr_market.KOSDAQ",
+                },
+                required=False,
+                category=FieldCategory.PARAMETERS,
+                expression_mode=ExpressionMode.FIXED_ONLY,
+                example="all",
+                expected_type="str",
+            ),
+            "limit": FieldSchema(
+                name="limit",
+                type=FieldType.INTEGER,
+                description="i18n:fields.KoreaStockRankingNode.limit",
+                default=20,
+                min_value=RANKING_LIMIT_MIN,
+                max_value=RANKING_LIMIT_MAX,
+                required=False,
+                category=FieldCategory.PARAMETERS,
+                expression_mode=ExpressionMode.FIXED_ONLY,
+                example=20,
+                expected_type="int",
+            ),
+        }
+
+    async def execute(self, context: Any) -> Dict[str, Any]:
+        """Fail closed on an engine without the ranking executor.
+
+        programgarden 2.6.6+ executes this node with its ranking
+        executor and never calls this method (see ``RANKING_MIN_ENGINE``).
+        """
+        raise ranking_engine_required(self.type)

programgarden_core-2.6.3/programgarden_core/nodes/ranking_stock.py

@@ -0,0 +1,248 @@
+"""
+ProgramGarden Core - Overseas Stock Ranking Node
+
+해외주식 순위 조회:
+- OverseasStockRankingNode: 미국 주식 등락률·거래량·거래대금·회전율·시가총액·52주 신고가/신저가 순위 (LS g3112)
+"""
+
+from typing import Any, ClassVar, Dict, List, Literal, Optional, TYPE_CHECKING
+
+from pydantic import Field
+
+if TYPE_CHECKING:
+    from programgarden_core.models.field_binding import FieldSchema
+
+from programgarden_core.nodes.base import (
+    BaseNode,
+    BrokerProvider,
+    InputPort,
+    NodeCategory,
+    OVERSEAS_STOCK_RANKING_FIELDS,
+    OVERSEAS_STOCK_RANKING_SYMBOL_FIELDS,
+    OutputPort,
+    ProductScope,
+)
+from programgarden_core.nodes.ranking_korea_stock import RANKING_LIMIT_MAX, RANKING_LIMIT_MIN, ranking_engine_required
+
+
+# Node enum → g3112 rankgubun (LS guide: 0 상승률, 1 하락률, 2 거래량, 3 거래대금, 4 회전율,
+# 5 시가총액, 6 52주신고가, 7 52주신저가). '8' 상한가 / '9' 하한가 are intentionally not exposed.
+OVERSEAS_RANKING_TYPES = [
+    "change_rate_up", "change_rate_down", "volume", "trading_value",
+    "turnover", "market_cap", "high_52w", "low_52w",
+]
+# Node enum → g3112 exgubun (LS guide: 1 전체, 2 뉴욕, 3 나스닥, 4 ETF).
+OVERSEAS_RANKING_MARKETS = ["all", "NYSE", "NASDAQ", "ETF"]
+
+
+_BROKER_CREDENTIAL = {
+    "credential_id": "broker_cred",
+    "type": "broker_ls_overseas_stock",
+    "data": [
+        {"key": "appkey", "value": "", "type": "password", "label": "App Key"},
+        {"key": "appsecret", "value": "", "type": "password", "label": "App Secret"},
+    ],
+}
+
+
+class OverseasStockRankingNode(BaseNode):
+    """
+    해외주식 순위 노드
+
+    미국 주식의 등락률·거래량·거래대금·회전율·시가총액·52주 신고가/신저가 순위를
+    LS g3112(해외주식API시세순위)로 조회합니다. 읽기 전용이며 주문을 내지 않습니다.
+    """
+
+    type: Literal["OverseasStockRankingNode"] = "OverseasStockRankingNode"
+    category: NodeCategory = NodeCategory.MARKET
+    description: str = "i18n:nodes.OverseasStockRankingNode.description"
+    _img_url: ClassVar[str] = ""
+    _product_scope: ClassVar[ProductScope] = ProductScope.STOCK
+    _broker_provider: ClassVar[BrokerProvider] = BrokerProvider.LS
+
+    ranking_type: str = Field(
+        default="change_rate_up",
+        description="Ranking: change_rate_up, change_rate_down, volume, trading_value, turnover, market_cap, high_52w, low_52w",
+    )
+    market: str = Field(
+        default="all",
+        description="US segment: all, NYSE, NASDAQ, ETF",
+    )
+    limit: int = Field(
+        default=20,
+        ge=RANKING_LIMIT_MIN,
+        le=RANKING_LIMIT_MAX,
+        description="Maximum number of ranked rows (1-100)",
+    )
+
+    _usage: ClassVar[Dict[str, Any]] = {
+        "when_to_use": [
+            "Pick today's top US gainers, losers, most traded, largest or 52-week-high stocks as a candidate list",
+            "Start a US screen from the whole market or one segment (NYSE, NASDAQ, ETF) instead of a fixed watchlist",
+        ],
+        "when_not_to_use": [
+            "For the full listed US universe — use OverseasStockSymbolQueryNode",
+            "For domestic stocks — use KoreaStockRankingNode",
+            "For overseas futures — there is no LS ranking query; pick a contract with FuturesContractNode",
+        ],
+        "typical_scenarios": [
+            "OverseasStockRankingNode(volume) → CodeNode (filter) → OverseasStockMarketDataNode",
+            "OverseasStockRankingNode(high_52w, NASDAQ) → TableDisplayNode",
+            "OverseasStockRankingNode.symbols → SplitNode → OverseasStockHistoricalDataNode",
+        ],
+    }
+    _features: ClassVar[List[str]] = [
+        "LS g3112 (해외주식API시세순위), US only; ranking types map to the LS rank codes 0-7",
+        "Outputs `rankings` (full rows), `symbols` (OverseasStock symbol list) and `count`",
+        "Exchange comes from the LS key symbol prefix (81 NYSE/AMEX shown as NYSE, 82 NASDAQ); rows without it keep exchange=null and are left out of `symbols`",
+        "Numbers are parsed exactly from LS strings; units of trading value and market cap are not declared by LS and are not converted",
+        "Pages with cts_value up to `limit` rows, at most 5 requests at 1 request per second",
+        "Read-only; overseas stock has no paper trading. Deep validation and dry runs return 3 synthetic rows and make no broker call",
+    ]
+    _anti_patterns: ClassVar[List[Dict[str, str]]] = [
+        {
+            "pattern": "Wiring `symbols` or `rankings` straight into OverseasStockNewOrderNode",
+            "reason": "A ranking is a moving market snapshot, not a trading decision; top movers include thin or halted-adjacent issues.",
+            "alternative": "Filter in a CodeNode or ConditionNode (price, change, holdings, budget) and order at most the chosen symbol.",
+        },
+        {
+            "pattern": "Treating a row with exchange=null as NYSE or NASDAQ",
+            "reason": "The exchange could not be read from the LS key symbol; guessing routes orders to the wrong market.",
+            "alternative": "Use the `symbols` output, which keeps only rows with a known exchange.",
+        },
+    ]
+    _examples: ClassVar[List[Dict[str, Any]]] = [
+        {
+            "title": "Top 20 US gainers",
+            "description": "List today's 20 biggest US gainers across all segments.",
+            "workflow_snippet": {
+                "id": "overseas_stock_ranking_gainers",
+                "name": "US Top Gainers",
+                "nodes": [
+                    {"id": "start", "type": "StartNode"},
+                    {"id": "broker", "type": "OverseasStockBrokerNode", "credential_id": "broker_cred"},
+                    {"id": "ranking", "type": "OverseasStockRankingNode", "ranking_type": "change_rate_up", "market": "all", "limit": 20},
+                    {"id": "display", "type": "TableDisplayNode", "data": "{{ nodes.ranking.rankings }}"},
+                ],
+                "edges": [
+                    {"from": "start", "to": "broker"},
+                    {"from": "broker", "to": "ranking"},
+                    {"from": "ranking", "to": "display"},
+                ],
+                "credentials": [_BROKER_CREDENTIAL],
+            },
+            "expected_output": "rankings: [{rank, symbol, exchange, name, price, change_pct, volume, ...}] (up to 20 rows).",
+        },
+        {
+            "title": "NASDAQ volume leaders to quotes",
+            "description": "Take the 10 most traded NASDAQ stocks and read their current quotes.",
+            "workflow_snippet": {
+                "id": "overseas_stock_ranking_volume",
+                "name": "NASDAQ Volume Leaders",
+                "nodes": [
+                    {"id": "start", "type": "StartNode"},
+                    {"id": "broker", "type": "OverseasStockBrokerNode", "credential_id": "broker_cred"},
+                    {"id": "ranking", "type": "OverseasStockRankingNode", "ranking_type": "volume", "market": "NASDAQ", "limit": 10},
+                    {"id": "quotes", "type": "OverseasStockMarketDataNode", "symbols": "{{ nodes.ranking.symbols }}"},
+                    {"id": "display", "type": "TableDisplayNode", "data": "{{ nodes.quotes.values }}"},
+                ],
+                "edges": [
+                    {"from": "start", "to": "broker"},
+                    {"from": "broker", "to": "ranking"},
+                    {"from": "ranking", "to": "quotes"},
+                    {"from": "quotes", "to": "display"},
+                ],
+                "credentials": [_BROKER_CREDENTIAL],
+            },
+            "expected_output": "quotes.values: current quotes for up to 10 NASDAQ volume leaders.",
+        },
+    ]
+    _node_guide: ClassVar[Dict[str, Any]] = {
+        "input_handling": (
+            "No symbol input. Choose ranking_type (change_rate_up, change_rate_down, volume, trading_value, turnover, "
+            "market_cap, high_52w, low_52w), market (all, NYSE, NASDAQ, ETF) and limit (1-100). "
+            "A connected OverseasStockBrokerNode supplies the connection automatically."
+        ),
+        "output_consumption": (
+            "`rankings` rows: rank, symbol, exchange (NYSE/NASDAQ or null), exchange_source (keysymbol/unavailable), "
+            "name (Korean name), exchange_name, keysymbol, price, sign (raw), change and change_pct (signed), volume, "
+            "trading_value + trading_value_unit (as_returned), turnover, market_cap + market_cap_unit (as_returned), "
+            "high_52w, low_52w, product (overseas_stock), source_tr (g3112). Empty LS strings become null. "
+            "`symbols` items: {exchange, symbol, name, product} for rows with a known exchange. `count`: number of rankings rows. "
+            "Deep validation and dry runs emit 3 synthetic rows (AAPL, MSFT, NVDA) with this exact shape and no broker call."
+        ),
+        "common_combinations": [
+            "OverseasStockRankingNode.symbols → OverseasStockMarketDataNode",
+            "OverseasStockRankingNode.rankings → CodeNode (decision)",
+            "OverseasStockRankingNode.rankings → TableDisplayNode",
+        ],
+        "pitfalls": [
+            "The exchange code 81 covers both NYSE and AMEX; it is shown as NYSE",
+            "Trading value and market cap units are not declared by LS; compare only within one result",
+            "LS failures raise with the TR code first (e.g. 'g3112: <code> <message>')",
+        ],
+    }
+
+    _inputs: List[InputPort] = []
+    _outputs: List[OutputPort] = [
+        OutputPort(name="rankings", type="array", description="i18n:ports.rankings", fields=OVERSEAS_STOCK_RANKING_FIELDS),
+        OutputPort(name="symbols", type="symbol_list", description="i18n:ports.symbols", fields=OVERSEAS_STOCK_RANKING_SYMBOL_FIELDS),
+        OutputPort(name="count", type="integer", description="i18n:ports.count"),
+    ]
+
+    _version: ClassVar[str] = "1.0.0"
+    _updated_at: ClassVar[str] = "2026-10-15"
+    _change_note: ClassVar[Optional[str]] = "New: US stock rankings by change, volume, value, turnover, market cap, 52-week (LS g3112)."
+
+    @classmethod
+    def get_field_schema(cls) -> Dict[str, "FieldSchema"]:
+        from programgarden_core.models.field_binding import ExpressionMode, FieldCategory, FieldSchema, FieldType
+        return {
+            "ranking_type": FieldSchema(
+                name="ranking_type",
+                type=FieldType.ENUM,
+                description="i18n:fields.OverseasStockRankingNode.ranking_type",
+                default="change_rate_up",
+                enum_values=list(OVERSEAS_RANKING_TYPES),
+                enum_labels={value: f"i18n:enums.ranking_type.{value}" for value in OVERSEAS_RANKING_TYPES},
+                required=False,
+                category=FieldCategory.PARAMETERS,
+                expression_mode=ExpressionMode.FIXED_ONLY,
+                example="change_rate_up",
+                expected_type="str",
+            ),
+            "market": FieldSchema(
+                name="market",
+                type=FieldType.ENUM,
+                description="i18n:fields.OverseasStockRankingNode.market",
+                default="all",
+                enum_values=list(OVERSEAS_RANKING_MARKETS),
+                enum_labels={value: f"i18n:enums.us_ranking_market.{value}" for value in OVERSEAS_RANKING_MARKETS},
+                required=False,
+                category=FieldCategory.PARAMETERS,
+                expression_mode=ExpressionMode.FIXED_ONLY,
+                example="all",
+                expected_type="str",
+            ),
+            "limit": FieldSchema(
+                name="limit",
+                type=FieldType.INTEGER,
+                description="i18n:fields.OverseasStockRankingNode.limit",
+                default=20,
+                min_value=RANKING_LIMIT_MIN,
+                max_value=RANKING_LIMIT_MAX,
+                required=False,
+                category=FieldCategory.PARAMETERS,
+                expression_mode=ExpressionMode.FIXED_ONLY,
+                example=20,
+                expected_type="int",
+            ),
+        }
+
+    async def execute(self, context: Any) -> Dict[str, Any]:
+        """Fail closed on an engine without the ranking executor.
+
+        programgarden 2.6.6+ executes this node with its ranking executor and
+        never calls this method (see ``ranking_korea_stock.RANKING_MIN_ENGINE``).
+        """
+        raise ranking_engine_required(self.type)

{programgarden_core-2.6.2 → programgarden_core-2.6.3}/programgarden_core/registry/node_registry.py

@@ -207,6 +207,7 @@ class NodeTypeRegistry:
             KoreaStockAccountNode, KoreaStockOpenOrdersNode,
             KoreaStockMarketDataNode, KoreaStockFundamentalNode,
             KoreaStockHistoricalDataNode, KoreaStockSymbolQueryNode,
+            KoreaStockRankingNode, OverseasStockRankingNode,
             KoreaStockRealMarketDataNode, KoreaStockRealAccountNode, KoreaStockRealOrderEventNode,
             KoreaStockNewOrderNode, KoreaStockModifyOrderNode, KoreaStockCancelOrderNode,
             # Data (상품 무관)
@@ -251,6 +252,7 @@ class NodeTypeRegistry:
             KoreaStockAccountNode, KoreaStockOpenOrdersNode,
             KoreaStockMarketDataNode, KoreaStockFundamentalNode,
             KoreaStockHistoricalDataNode, KoreaStockSymbolQueryNode,
+            KoreaStockRankingNode, OverseasStockRankingNode,
             KoreaStockRealMarketDataNode, KoreaStockRealAccountNode, KoreaStockRealOrderEventNode,
             KoreaStockNewOrderNode, KoreaStockModifyOrderNode, KoreaStockCancelOrderNode,
             # Data (상품 무관)

{programgarden_core-2.6.2 → programgarden_core-2.6.3}/pyproject.toml

@@ -5,7 +5,7 @@ authors = [
 homepage = "https://programgarden.com"
 requires-python = ">=3.12"
 name = "programgarden-core"
-version = "2.6.2"
+version = "2.6.3"
 license = "AGPL-3.0-or-later"
 description = "ProgramGarden Core - 노드 기반 DSL 핵심 타입 정의"
 readme = "README.md"