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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: programgarden-core
-Version: 2.6.1
+Version: 2.6.3
 Summary: ProgramGarden Core - 노드 기반 DSL 핵심 타입 정의
 License-Expression: AGPL-3.0-or-later
 Author: 프로그램동산
@@ -15,6 +15,8 @@ Requires-Dist: pydantic (>=2.0.1,<3.0.0)
 Requires-Dist: tzdata (>=2025.2,<2026.0)
 Description-Content-Type: text/markdown
 
+The 2.6.2 release candidate [futures minute alias correction](../../docs/futures-minute-alias-contract.md) aligns canonical minute periods with the existing one-page o3103 path and rejects unsupported hourly/adjustment claims. Complete-range coverage and consumer adoption are not implied.
+
 US regular-session requests can opt into SessionGateNode.exchange_calendar (XNYS/XNAS) for scheduled holidays and early closes. See [session gates](../../docs/session-gates-and-guarded-split.md).
 
 # ProgramGarden Core
@@ -58,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 |
@@ -74,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.1 → programgarden_core-2.6.3}/README.md

@@ -1,3 +1,5 @@
+The 2.6.2 release candidate [futures minute alias correction](../../docs/futures-minute-alias-contract.md) aligns canonical minute periods with the existing one-page o3103 path and rejects unsupported hourly/adjustment claims. Complete-range coverage and consumer adoption are not implied.
+
 US regular-session requests can opt into SessionGateNode.exchange_calendar (XNYS/XNAS) for scheduled holidays and early closes. See [session gates](../../docs/session-gates-and-guarded-split.md).
 
 # ProgramGarden Core
@@ -41,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 |
@@ -57,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.1 → 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.1 → 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.",
@@ -116,7 +120,7 @@
   "nodes.OverseasFuturesBrokerNode.name": "Futures Broker",
   "nodes.OverseasFuturesCancelOrderNode.description": "Cancels a pending overseas futures order by its original order ID. Requires original_order_id from FuturesOpenOrdersNode or FuturesRealOrderEventNode. Outputs cancel result and cancelled order ID. Rate-limited to 5-second minimum interval. Typical connection: FuturesOpenOrdersNode → FuturesCancelOrderNode.",
   "nodes.OverseasFuturesCancelOrderNode.name": "Futures Cancel Order",
-  "nodes.OverseasFuturesHistoricalDataNode.description": "Fetches historical OHLCV chart data for overseas futures over a specified date range. Supports bar intervals from 1-minute to monthly. Enable 'adjust' for rollover-adjusted prices (recommended for backtesting). Auto-iterates when previous node outputs multiple symbols. Requires an upstream OverseasFuturesBrokerNode. Typical connection: FuturesSymbolQueryNode → FuturesHistoricalDataNode → ConditionNode or → BacktestEngineNode. Supported exchanges: CME, EUREX, SGX, HKEX. Can be used as an AI Agent tool.",
+  "nodes.OverseasFuturesHistoricalDataNode.description": "Fetches exact-contract overseas-futures OHLCV through an upstream broker. Minute periods use one available o3103 page (200 rows requested); start/end dates are not sent and the requested period is not certified coverage. Completed bars, time zone, retention and sufficient lookback require separate verification. Daily/weekly/monthly use o3108. Rollover adjustment is not implemented; keep adjust=false.",
   "nodes.OverseasFuturesHistoricalDataNode.name": "Futures Historical Data",
   "nodes.OverseasFuturesMarketDataNode.description": "Fetches the current price, volume, and market data for a single overseas futures symbol as a one-time REST API call. Auto-iterates when the previous node outputs an array of symbols. Outputs market data including last price, change, volume, and bid/ask. Requires an upstream OverseasFuturesBrokerNode. Supported exchanges: CME, EUREX, SGX, HKEX. For continuous updates, use OverseasFuturesRealMarketDataNode. Can be used as an AI Agent tool.",
   "nodes.OverseasFuturesMarketDataNode.name": "Futures Market Data",
@@ -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",
@@ -371,13 +381,13 @@
   "fields.OverseasFuturesCancelOrderNode.exchange": "Select the exchange.",
   "fields.OverseasFuturesCancelOrderNode.original_order_id": "Original order ID to cancel.",
   "fields.OverseasFuturesCancelOrderNode.symbol": "Symbol code.",
-  "fields.OverseasFuturesHistoricalDataNode.adjust.detail": "Uses adjusted prices reflecting rollovers, etc. Recommended for backtesting.",
-  "fields.OverseasFuturesHistoricalDataNode.adjust.short": "Apply adjusted price",
+  "fields.OverseasFuturesHistoricalDataNode.adjust.detail": "Must remain false. Rollover adjustment and cross-contract stitching are not implemented; true is rejected before broker access.",
+  "fields.OverseasFuturesHistoricalDataNode.adjust.short": "Exact-contract prices only (false)",
   "fields.OverseasFuturesHistoricalDataNode.end_date": "End date (YYYYMMDD)",
-  "fields.OverseasFuturesHistoricalDataNode.end_date.help_text": "e.g., 20241231. With binding: {{ date.today(format='yyyymmdd') }}",
-  "fields.OverseasFuturesHistoricalDataNode.interval": "Bar interval (1m, 5m, 15m, 1h, 1d, 1w, 1M)",
+  "fields.OverseasFuturesHistoricalDataNode.end_date.help_text": "e.g., 20241231. With binding: {{ date.today(format='yyyymmdd') }}. Minute queries do not send this date; the requested period is not actual coverage.",
+  "fields.OverseasFuturesHistoricalDataNode.interval": "Implemented periods: 30s, 1m, 5m, 15m, 30m, 1d, 1w, 1M. Hourly and unknown periods are rejected.",
   "fields.OverseasFuturesHistoricalDataNode.start_date": "Start date (YYYYMMDD)",
-  "fields.OverseasFuturesHistoricalDataNode.start_date.help_text": "e.g., 20240101. With binding: {{ date.ago(30, format='yyyymmdd') }}",
+  "fields.OverseasFuturesHistoricalDataNode.start_date.help_text": "e.g., 20240101. With binding: {{ date.ago(30, format='yyyymmdd') }}. Used by daily/weekly/monthly requests; minute queries do not send this date and return one available page.",
   "fields.OverseasFuturesHistoricalDataNode.symbol": "Enter the futures symbol code to query",
   "fields.OverseasFuturesHistoricalDataNode.symbol.exchange": "Exchange",
   "fields.OverseasFuturesHistoricalDataNode.symbol.help_text": "Direct input or binding available (fx toggle)",
@@ -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",
@@ -1035,6 +1064,8 @@
   "enums.interval.1Y": "1 year",
   "enums.interval.1d": "1 Day",
   "enums.interval.1h": "1 Hour",
+  "enums.interval.30s": "30 seconds",
+  "enums.interval.30m": "30 minutes",
   "enums.interval.1m": "1 Minute",
   "enums.interval.1w": "1 Week",
   "enums.interval.5m": "5 Minutes",

{programgarden_core-2.6.1 → 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.",
@@ -116,7 +120,7 @@
   "nodes.OverseasFuturesBrokerNode.name": "해외선물 브로커",
   "nodes.OverseasFuturesCancelOrderNode.description": "해외선물 미체결 주문을 원래 주문 ID로 취소합니다. FuturesOpenOrdersNode 또는 FuturesRealOrderEventNode에서 original_order_id를 받아야 합니다. 출력: 취소 결과, 취소된 주문 ID. 최소 5초 간격 제한 적용. 일반적인 연결: FuturesOpenOrdersNode → FuturesCancelOrderNode.",
   "nodes.OverseasFuturesCancelOrderNode.name": "해외선물 취소주문",
-  "nodes.OverseasFuturesHistoricalDataNode.description": "지정 기간의 해외선물 과거 OHLCV 차트 데이터를 조회합니다. 1분봉부터 월봉까지 지원합니다. 롤오버 수정가(adjust) 활성화 권장(백테스트용). 이전 노드가 여러 종목을 출력하면 자동 반복 실행. 상위 OverseasFuturesBrokerNode 연결 필수. 일반적인 연결: FuturesSymbolQueryNode → FuturesHistoricalDataNode → ConditionNode 또는 → BacktestEngineNode. 지원 거래소: CME, EUREX, SGX, HKEX. AI Agent 도구로 사용 가능.",
+  "nodes.OverseasFuturesHistoricalDataNode.description": "연결한 증권 계좌로 지정 월물의 OHLCV를 조회합니다. 분봉은 o3103의 첫 페이지를 한 번 조회하며 200건을 요청합니다. 분봉 요청에는 시작·종료 날짜가 전송되지 않으며, 표시된 요청 기간 전체를 조회했다는 뜻이 아닙니다. 완료봉·시간대·보존 범위·필요 봉 수는 별도로 확인해야 합니다. 일·주·월봉은 o3108을 사용합니다. 롤오버 가격 보정은 구현되어 있지 않아 adjust는 false로 유지합니다.",
   "nodes.OverseasFuturesHistoricalDataNode.name": "해외선물 과거데이터",
   "nodes.OverseasFuturesMarketDataNode.description": "해외선물 종목의 현재가, 거래량, 시세 데이터를 REST API 1회 호출로 조회합니다. 이전 노드가 종목 배열을 출력하면 자동 반복 실행합니다. 출력: 최근 체결가, 등락폭, 거래량, 매수/매도 호가. 상위 OverseasFuturesBrokerNode 연결 필수. 지원 거래소: CME, EUREX, SGX, HKEX. 연속 업데이트가 필요하면 OverseasFuturesRealMarketDataNode를 사용하세요. AI Agent 도구로 사용 가능.",
   "nodes.OverseasFuturesMarketDataNode.name": "해외선물 현재가",
@@ -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",
@@ -371,13 +381,13 @@
   "fields.OverseasFuturesCancelOrderNode.exchange": "거래소를 선택합니다.",
   "fields.OverseasFuturesCancelOrderNode.original_order_id": "취소할 원주문번호입니다.",
   "fields.OverseasFuturesCancelOrderNode.symbol": "종목 코드입니다.",
-  "fields.OverseasFuturesHistoricalDataNode.adjust.detail": "롤오버 등 반영된 수정 가격을 사용합니다. 백테스트 시 권장합니다.",
-  "fields.OverseasFuturesHistoricalDataNode.adjust.short": "수정주가 적용 여부",
+  "fields.OverseasFuturesHistoricalDataNode.adjust.detail": "false로 유지합니다. 롤오버 가격 보정과 월물 연결은 구현되어 있지 않으며, true는 증권사 접근 전에 거절됩니다.",
+  "fields.OverseasFuturesHistoricalDataNode.adjust.short": "지정 월물 가격만 사용 (false)",
   "fields.OverseasFuturesHistoricalDataNode.end_date": "조회 종료일 (YYYYMMDD)",
-  "fields.OverseasFuturesHistoricalDataNode.end_date.help_text": "예: 20241231. 바인딩 시 {{ date.today(format='yyyymmdd') }} 사용 가능",
-  "fields.OverseasFuturesHistoricalDataNode.interval": "봉 종류 (1m, 5m, 15m, 1h, 1d, 1w, 1M)",
+  "fields.OverseasFuturesHistoricalDataNode.end_date.help_text": "예: 20241231. 바인딩: {{ date.today(format='yyyymmdd') }}. 분봉은 이 날짜를 전송하지 않으며, 표시된 요청 기간이 실제 조회 범위를 보장하지 않습니다.",
+  "fields.OverseasFuturesHistoricalDataNode.interval": "지원 주기: 30s, 1m, 5m, 15m, 30m, 1d, 1w, 1M. 1h와 알 수 없는 주기는 거절됩니다.",
   "fields.OverseasFuturesHistoricalDataNode.start_date": "조회 시작일 (YYYYMMDD)",
-  "fields.OverseasFuturesHistoricalDataNode.start_date.help_text": "예: 20240101. 바인딩 시 {{ date.ago(30, format='yyyymmdd') }} 사용 가능",
+  "fields.OverseasFuturesHistoricalDataNode.start_date.help_text": "예: 20240101. 바인딩: {{ date.ago(30, format='yyyymmdd') }}. 일·주·월봉 요청에 사용합니다. 분봉은 이 날짜를 전송하지 않고 첫 페이지를 한 번 조회합니다.",
   "fields.OverseasFuturesHistoricalDataNode.symbol": "조회할 선물 종목 코드를 입력하세요",
   "fields.OverseasFuturesHistoricalDataNode.symbol.exchange": "거래소",
   "fields.OverseasFuturesHistoricalDataNode.symbol.help_text": "직접 입력 또는 바인딩 가능 (fx 토글)",
@@ -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)",
@@ -1035,6 +1064,8 @@
   "enums.interval.1Y": "1년",
   "enums.interval.1d": "1일",
   "enums.interval.1h": "1시간",
+  "enums.interval.30s": "30초",
+  "enums.interval.30m": "30분",
   "enums.interval.1m": "1분",
   "enums.interval.1w": "1주",
   "enums.interval.5m": "5분",

{programgarden_core-2.6.1 → 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.1 → programgarden_core-2.6.3}/programgarden_core/nodes/backtest_futures.py

@@ -10,7 +10,7 @@ Item-based execution:
 """
 
 from typing import Any, Optional, List, Literal, Dict, ClassVar, TYPE_CHECKING
-from pydantic import Field
+from pydantic import Field, field_validator
 
 if TYPE_CHECKING:
     from programgarden_core.models.field_binding import FieldSchema
@@ -59,21 +59,27 @@ class OverseasFuturesHistoricalDataNode(BaseNode):
     )
     start_date: str = Field(
         default="{{ date.months_ago(3, format='yyyymmdd') }}",
-        description="Start date (YYYY-MM-DD or {{ date.months_ago(N, format='yyyymmdd') }})",
+        description="Requested start date (YYYYMMDD or expression); not sent for minute periods.",
     )
     end_date: str = Field(
         default="{{ date.today(format='yyyymmdd') }}",
-        description="End date (YYYY-MM-DD or {{ date.today(format='yyyymmdd') }})",
+        description="Requested end date (YYYYMMDD or expression); not sent for minute periods.",
     )
-    interval: str = Field(
+    interval: Literal["30s", "1m", "5m", "15m", "30m", "1d", "1w", "1M"] = Field(
         default="1d",
-        description="Data interval (1m, 5m, 15m, 1h, 1d)",
+        description="Implemented chart periods: 30s, 1m, 5m, 15m, 30m, 1d, 1w, 1M; hourly and unknown periods are rejected.",
     )
-    adjust: bool = Field(
+    adjust: Literal[False] = Field(
         default=False,
-        description="Apply adjusted prices",
+        description="Must remain false; only exact-contract prices are implemented, without rollover adjustment.",
     )
 
+    @field_validator("interval", mode="before")
+    @classmethod
+    def normalize_legacy_interval(cls, value):
+        aliases = {"1min": "1m", "5min": "5m", "15min": "15m", "30min": "30m"}
+        return aliases.get(value, value) if isinstance(value, str) else value
+
     @classmethod
     def is_tool_enabled(cls) -> bool:
         return True
@@ -82,7 +88,7 @@ class OverseasFuturesHistoricalDataNode(BaseNode):
         "when_to_use": [
             "Retrieve daily (or intraday) OHLCV history for an overseas futures contract (CME, EUREX, SGX, HKEX) for technical analysis or backtesting",
             "Feed historical candles into ConditionNode plugins (MACD, Bollinger, etc.) that operate on futures price series",
-            "Use `{{ date.ago(N, format='yyyymmdd') }}` for start_date to maintain a rolling lookback window",
+            "Use date expressions for daily/weekly/monthly request dates; minute requests do not send dates or guarantee a lookback window",
         ],
         "when_not_to_use": [
             "For overseas stock historical data — use OverseasStockHistoricalDataNode",
@@ -97,9 +103,11 @@ class OverseasFuturesHistoricalDataNode(BaseNode):
     }
     _features: ClassVar[List[str]] = [
         "Returns time_series list of OHLCV candles: [{date, open, high, low, close, volume}, ...] ordered oldest-first",
-        "Supports intervals: 1m, 5m, 15m, 1h, 1d, 1w, 1M — daily is the default for swing/position strategies",
+        "Supports implemented periods: 30s, 1m, 5m, 15m, 30m, 1d, 1w, 1M; legacy minute aliases are accepted; 1h and unknown periods are rejected",
         "start_date / end_date accept YYYYMMDD strings or `{{ date.ago(N, format='yyyymmdd') }}` expressions",
-        "adjust=True applies roll-adjusted prices for continuous contract backtesting",
+        "adjust must remain false: exact-contract prices only, without rollover adjustment or month stitching",
+        "Minute history returns the available initial o3103 page (200 rows requested), not a complete requested range or a guaranteed latest-N set",
+        "Minute start/end dates are not sent to o3103; period echoes requested dates, not actual coverage. Bar finality, time zone, retention and sufficient lookback require separate evidence",
         "is_tool_enabled=True — AI Agent can fetch futures history for technical analysis autonomously",
         "Item-based execution: pair with SplitNode to fetch OHLCV for multiple contracts",
         "Replay resolves this node's request with the upstream broker's connection identity (provider, product, paper_trading, broker_node_id, and credential_id when the account is linked); a recording whose request omits that connection does not match",
@@ -117,9 +125,9 @@ class OverseasFuturesHistoricalDataNode(BaseNode):
             "alternative": "Bind `{{ nodes.historical.value.time_series }}` to the ConditionNode data field.",
         },
         {
-            "pattern": "Using adjust=False for a continuous contract strategy that spans roll periods",
-            "reason": "Unadjusted prices have discontinuities at contract roll dates, which distort momentum and mean-reversion signals.",
-            "alternative": "Set adjust=True for strategies that look back across multiple roll periods.",
+            "pattern": "Treating exact-contract observations as continuous or rollover-adjusted data",
+            "reason": "Rollover adjustment and cross-contract stitching are not implemented.",
+            "alternative": "Keep adjust=False and verify this contract has the needed data; do not substitute internal history.",
         },
     ]
     _examples: ClassVar[List[Dict[str, Any]]] = [
@@ -158,7 +166,7 @@ class OverseasFuturesHistoricalDataNode(BaseNode):
         },
         {
             "title": "HKEX mini-futures intraday scan",
-            "description": "Fetch 1-hour bars for the past 10 days for HKEX mini-futures and apply MACD.",
+            "description": "Request the available initial 30-minute page for HKEX mini-futures; verify completed bars and lookback before MACD.",
             "workflow_snippet": {
                 "id": "overseas_futures_historical_hkex_macd",
                 "name": "HKEX Intraday MACD",
@@ -166,7 +174,7 @@ class OverseasFuturesHistoricalDataNode(BaseNode):
                     {"id": "start", "type": "StartNode"},
                     {"id": "broker", "type": "OverseasFuturesBrokerNode", "credential_id": "broker_cred", "paper_trading": False},
                     {'id': 'split', 'type': 'SplitNode', 'array': [{'symbol': 'MHIH26', 'exchange': 'HKEX'}]},
-                    {"id": "historical", "type": "OverseasFuturesHistoricalDataNode", "symbol": "{{ nodes.split.item }}", "start_date": "{{ date.ago(10, format='yyyymmdd') }}", "end_date": "{{ date.today(format='yyyymmdd') }}", "interval": "1h", "adjust": False},
+                    {"id": "historical", "type": "OverseasFuturesHistoricalDataNode", "symbol": "{{ nodes.split.item }}", "start_date": "{{ date.ago(10, format='yyyymmdd') }}", "end_date": "{{ date.today(format='yyyymmdd') }}", "interval": "30m", "adjust": False},
                     {"id": "condition", "type": "ConditionNode", "plugin": "MACD", "items": {"from": "{{ item.time_series }}", "extract": {"symbol": "{{ item.symbol }}", "exchange": "{{ item.exchange }}", "date": "{{ row.date }}", "close": "{{ row.close }}"}}, "fields": {"fast": 12, "slow": 26, "signal": 9, "direction": "bullish_cross"}},
                 {'id': 'split_results', 'type': 'AggregateNode', 'mode': 'collect'}],
                 "edges": [
@@ -187,7 +195,7 @@ class OverseasFuturesHistoricalDataNode(BaseNode):
                     }
                 ],
             },
-            "expected_output": "MACD crossover signal computed from 1-hour HKEX mini-futures bars; result port emits buy/sell signal.",
+            "expected_output": "Available 30-minute observations only; complete range, finality and sufficient lookback are not certified.",
         },
     ]
     _node_guide: ClassVar[Dict[str, Any]] = {
@@ -195,7 +203,7 @@ class OverseasFuturesHistoricalDataNode(BaseNode):
             "The `symbol` field takes a single {exchange, symbol} dict — bind to `{{ nodes.split.item }}` for multi-contract iteration. "
             "Exchange values: CME, EUREX, SGX, HKEX. Symbol includes contract month code (e.g., ESH26). "
             "start_date / end_date: use `{{ date.ago(N, format='yyyymmdd') }}` for rolling lookback. "
-            "interval options: 1m, 5m, 15m, 1h, 1d, 1w, 1M."
+            "interval options: 30s, 1m, 5m, 15m, 30m, 1d, 1w, 1M. Minute queries return one available page, not a complete requested date range."
         ),
         "output_consumption": (
             "The `value` port emits {symbol, exchange, time_series: [{date, open, high, low, close, volume}, ...]}. "
@@ -221,9 +229,9 @@ class OverseasFuturesHistoricalDataNode(BaseNode):
         OutputPort(name="value", type="ohlcv_data", description="i18n:ports.ohlcv_value", fields=HISTORICAL_VALUE_FIELDS),
     ]
 
-    _version: ClassVar[str] = "1.0.0"
-    _updated_at: ClassVar[str] = "2026-05-19"
-    _change_note: ClassVar[Optional[str]] = None
+    _version: ClassVar[str] = "1.1.0"
+    _updated_at: ClassVar[str] = "2026-10-14"
+    _change_note: ClassVar[Optional[str]] = "Align minute aliases with one-page chart routing; reject unsupported periods and rollover adjustment."
 
     @classmethod
     def get_field_schema(cls) -> Dict[str, "FieldSchema"]:
@@ -296,12 +304,13 @@ class OverseasFuturesHistoricalDataNode(BaseNode):
                 description="i18n:fields.OverseasFuturesHistoricalDataNode.interval",
                 default="1d",
                 required=True,
-                enum_values=["1m", "5m", "15m", "1h", "1d", "1w", "1M"],
+                enum_values=["30s", "1m", "5m", "15m", "30m", "1d", "1w", "1M"],
                 enum_labels={
+                    "30s": "i18n:enums.interval.30s",
                     "1m": "i18n:enums.interval.1m",
                     "5m": "i18n:enums.interval.5m",
                     "15m": "i18n:enums.interval.15m",
-                    "1h": "i18n:enums.interval.1h",
+                    "30m": "i18n:enums.interval.30m",
                     "1d": "i18n:enums.interval.1d",
                     "1w": "i18n:enums.interval.1w",
                     "1M": "i18n:enums.interval.1M"
@@ -319,8 +328,9 @@ class OverseasFuturesHistoricalDataNode(BaseNode):
                 help_text="i18n:fields.OverseasFuturesHistoricalDataNode.adjust.detail",
                 default=False,
                 category=FieldCategory.PARAMETERS,
-                expression_mode=ExpressionMode.BOTH,
+                expression_mode=ExpressionMode.FIXED_ONLY,
                 ui_component=UIComponent.CHECKBOX,
-                example=True,
+                example=False,
+                expected_type="bool",
             ),
         }

{programgarden_core-2.6.1 → 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 등 — 주문에 쓰는 값)"},