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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: programgarden-core
-Version: 2.6.1
+Version: 2.6.2
 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

{programgarden_core-2.6.1 → programgarden_core-2.6.2}/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

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

@@ -116,7 +116,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",
@@ -371,13 +371,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)",
@@ -1035,6 +1035,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.2}/programgarden_core/i18n/locales/ko.json

@@ -116,7 +116,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": "해외선물 현재가",
@@ -371,13 +371,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 토글)",
@@ -1035,6 +1035,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.2}/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.2}/pyproject.toml

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