programgarden-core 2.5.1__tar.gz → 2.5.3__tar.gz

{programgarden_core-2.5.1 → programgarden_core-2.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: programgarden-core
-Version: 2.5.1
+Version: 2.5.3
 Summary: ProgramGarden Core - 노드 기반 DSL 핵심 타입 정의
 License-Expression: AGPL-3.0-or-later
 Author: 프로그램동산
@@ -10,12 +10,19 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: exchange-calendars (==4.13.2) ; python_version >= "3.12" and python_version < "4.0"
 Requires-Dist: pydantic (>=2.0.1,<3.0.0)
 Requires-Dist: tzdata (>=2025.2,<2026.0)
 Description-Content-Type: text/markdown
 
+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
 
+The REST overseas-stock position catalog declares `sellable_qty`, matching the
+broker-reported capacity preserved by the engine. Missing evidence remains null;
+see [the contract](../../docs/overseas-stock-sellable-quantity.md).
+
 ProgramGarden은 AI 시대에 맞춰 파이썬을 모르는 투자자도 개인화된 시스템 트레이딩을 자동으로 수행할 수 있게 돕는 오픈소스입니다. 본 저장소는 노드 기반 DSL의 핵심 타입, 베이스 클래스, 레지스트리, i18n을 정의하는 "코어" 모듈입니다.
 
 - 문서(비개발자 빠른 시작): https://programgarden.gitbook.io/docs/invest/non_dev_quick_guide

{programgarden_core-2.5.1 → programgarden_core-2.5.3}/README.md

@@ -1,5 +1,11 @@
+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
 
+The REST overseas-stock position catalog declares `sellable_qty`, matching the
+broker-reported capacity preserved by the engine. Missing evidence remains null;
+see [the contract](../../docs/overseas-stock-sellable-quantity.md).
+
 ProgramGarden은 AI 시대에 맞춰 파이썬을 모르는 투자자도 개인화된 시스템 트레이딩을 자동으로 수행할 수 있게 돕는 오픈소스입니다. 본 저장소는 노드 기반 DSL의 핵심 타입, 베이스 클래스, 레지스트리, i18n을 정의하는 "코어" 모듈입니다.
 
 - 문서(비개발자 빠른 시작): https://programgarden.gitbook.io/docs/invest/non_dev_quick_guide

{programgarden_core-2.5.1 → programgarden_core-2.5.3}/programgarden_core/i18n/locales/en.json

@@ -1266,6 +1266,7 @@
   "enums.query_type.new": "New",
   "enums.query_type.close": "Liquidation",
   "enums.query_type.total": "Total",
+  "nodes.SessionGateNode.exchange_calendar": "Optional scheduled regular-session calendar: XNYS (NYSE) or XNAS (Nasdaq). Intersects configured windows with holidays and early closes. Does not observe live halts.",
   "nodes.SessionGateNode.allowed": "True only inside a configured window; bind to IfNode.",
   "nodes.SessionGateNode.closed_dates": "Explicit YYYY-MM-DD exclusions. Either local calendar date or opening date blocks the window.",
   "nodes.SessionGateNode.days": "Allowed opening weekdays. The post-midnight portion belongs to the previous opening day.",

{programgarden_core-2.5.1 → programgarden_core-2.5.3}/programgarden_core/i18n/locales/ko.json

@@ -1266,6 +1266,7 @@
   "enums.query_type.new": "신규",
   "enums.query_type.close": "청산",
   "enums.query_type.total": "총가능",
+  "nodes.SessionGateNode.exchange_calendar": "미국 정규장 달력을 선택합니다. XNYS(뉴욕증권거래소) 또는 XNAS(나스닥)의 휴장일·조기폐장을 적용합니다. 실시간 거래정지는 확인하지 않습니다.",
   "nodes.SessionGateNode.allowed": "허용 구간 안에서만 true입니다. IfNode에 연결하세요.",
   "nodes.SessionGateNode.closed_dates": "YYYY-MM-DD 제외일 목록입니다. 현지 날짜 또는 구간 시작 날짜가 해당하면 차단합니다.",
   "nodes.SessionGateNode.days": "시작일 기준 허용 요일입니다. 자정 이후 구간은 전날의 시작 요일에 속합니다.",

programgarden_core-2.5.3/programgarden_core/market_calendar.py

@@ -0,0 +1,33 @@
+"""Scheduled US equity sessions, independent of credentials and live market data.
+
+This schedule includes published holidays and early closes. It cannot observe
+new emergency closures, instrument halts, or a broker's ability to accept orders.
+"""
+from datetime import datetime, timezone
+from functools import lru_cache
+from zoneinfo import ZoneInfo
+
+
+@lru_cache(maxsize=8)
+def _calendar(name: str, year: int):
+    import exchange_calendars
+
+    return exchange_calendars.get_calendar(
+        name, start=f"{year}-01-01", end=f"{year}-12-31", side="left",
+    )
+
+
+def scheduled_session_open(name: str, instant: datetime) -> bool:
+    """Exact seconds: opening is inclusive and closing is exclusive."""
+    if name not in {"XNYS", "XNAS"}:
+        raise ValueError("Unsupported exchange calendar")
+    if instant.tzinfo is None or instant.utcoffset() is None:
+        raise ValueError("Calendar clock must include timezone")
+    market_date = instant.astimezone(ZoneInfo("America/New_York")).date()
+    schedule = _calendar(name, market_date.year).schedule
+    day = market_date.isoformat()
+    if day not in schedule.index:
+        return False
+    row = schedule.loc[day]
+    clock = instant.astimezone(timezone.utc)
+    return bool(row["open"] <= clock < row["close"])

{programgarden_core-2.5.1 → programgarden_core-2.5.3}/programgarden_core/nodes/base.py

@@ -316,6 +316,7 @@ OVERSEAS_STOCK_POSITION_FIELDS: List[Dict[str, str]] = [
     {"name": "name", "type": "string", "description": "종목명"},
     {"name": "qty", "type": "number", "description": "보유 수량"},
     {"name": "quantity", "type": "number", "description": "보유 수량 (주문 노드 호환 별칭)"},
+    {"name": "sellable_qty", "type": "number", "description": "Observed COSOQ00201 sellable quantity; null when the broker field is absent"},
     {"name": "direction", "type": "string", "description": "포지션 방향 (주식은 항상 long)"},
     {"name": "close_side", "type": "string", "description": "청산 주문 방향 (주식은 항상 sell)"},
     {"name": "avg_price", "type": "number", "description": "평균 매입가"},

{programgarden_core-2.5.1 → programgarden_core-2.5.3}/programgarden_core/nodes/session_gate.py

@@ -32,8 +32,9 @@ class SessionWindow(BaseModel):
 class SessionGateNode(BaseNode):
     """Return a time decision immediately; use IfNode to enforce it.
 
-    This does not query an exchange calendar, infer holidays, wait for the next
-    session, or grant trading authority. Recheck near the order boundary.
+    An explicit exchange_calendar intersects the window with scheduled US
+    equity sessions. It does not observe live halts or grant trading authority.
+    Recheck near the order boundary.
     """
     type: Literal['SessionGateNode'] = 'SessionGateNode'
     category: NodeCategory = NodeCategory.SCHEDULE
@@ -42,6 +43,7 @@ class SessionGateNode(BaseNode):
     windows: list[SessionWindow] = Field(..., min_length=1, description='i18n:nodes.SessionGateNode.windows')
     days: list[Literal['mon','tue','wed','thu','fri','sat','sun']] = Field(..., min_length=1, description='i18n:nodes.SessionGateNode.days')
     closed_dates: list[str] = Field(default_factory=list, description='i18n:nodes.SessionGateNode.closed_dates')
+    exchange_calendar: Literal['XNYS', 'XNAS'] | None = Field(default=None, description='i18n:nodes.SessionGateNode.exchange_calendar')
 
     _inputs: list[InputPort] = [InputPort(name='trigger',type='signal',required=False,description='i18n:nodes.SessionGateNode.trigger')]
     _outputs: list[OutputPort] = [OutputPort(name=k,type=t,description=d) for k,t,d in [
@@ -51,21 +53,21 @@ class SessionGateNode(BaseNode):
         ('local_time','string','i18n:nodes.SessionGateNode.local_time'),
         ('reason','string','i18n:nodes.SessionGateNode.reason'),
     ]]
-    _change_note: ClassVar[str] = 'Add immediate DST-aware and overnight session decisions.'
-    _version: ClassVar[str] = '1.0.0'
-    _updated_at: ClassVar[str] = '2026-09-20'
+    _change_note: ClassVar[str] = 'Add opt-in scheduled US equity holidays and early closes.'
+    _version: ClassVar[str] = '1.1.0'
+    _updated_at: ClassVar[str] = '2026-09-29'
     _usage: ClassVar[dict[str,Any]] = {
         'when_to_use':['Check a market-local order window immediately before submission.','Handle overnight sessions, breaks and daylight-saving time.'],
-        'when_not_to_use':['An authoritative exchange-open or holiday feed is required.','Wait until opening: use TradingHoursFilterNode.'],
+        'when_not_to_use':['Live trading halts or new emergency closures must be observed.','Wait until opening: use TradingHoursFilterNode.'],
         'typical_scenarios':['ScheduleNode -> SessionGateNode -> IfNode(allowed) -> strategy','Reservation -> SessionGateNode -> IfNode(allowed) -> OrderNode'],
     }
-    _features: ClassVar[list[str]] = ['No credentials or network.','No sleeping and no dry-run bypass.','IANA timezone/DST and opening-weekday semantics.','Explicit IfNode controls downstream work.','Output is a pure function of the evaluation instant and the configuration (windows are start-inclusive and end-exclusive, plus days, closed_dates and the IANA timezone); replay evaluates it at the scenario as_of.','Two frames at the same instant produce the same allowed value; an outside-window scenario must sit at an instant outside the window.','allowed skips nothing by itself; bind it to an IfNode and hang the order chain on the IfNode true edge.']
+    _features: ClassVar[list[str]] = ['No credentials or network.', 'Optional exchange_calendar XNYS/XNAS intersects user windows with scheduled holidays and early closes; missing/broken calendar data blocks entry. Default null preserves explicit-window behavior.','No sleeping and no dry-run bypass.','IANA timezone/DST and opening-weekday semantics.','Explicit IfNode controls downstream work.','Output is a pure function of the evaluation instant and the configuration (windows are start-inclusive and end-exclusive, plus days, closed_dates and the IANA timezone); replay evaluates it at the scenario as_of.','Two frames at the same instant produce the same allowed value; an outside-window scenario must sit at an instant outside the window.','allowed skips nothing by itself; bind it to an IfNode and hang the order chain on the IfNode true edge.']
     _anti_patterns: ClassVar[list[dict[str,str]]] = [{'pattern':'Connect directly to an order and assume an ordinary edge checks allowed.','reason':'Edges sequence execution; false output does not automatically skip successors.','alternative':'Bind allowed to IfNode and use its true edge.'}]
     _node_guide: ClassVar[dict[str,Any]] = {
         'input_handling':'Configure timezone, windows, days and optional closed_dates. No current-time override is accepted from workflow data.',
         'output_consumption':'Bind nodes.session.allowed to an explicit IfNode; local_date can anchor completed-bar calculations.',
         'common_combinations':['ScheduleNode, IfNode, CodeNode, SQLiteNode, OrderNode'],
-        'pitfalls':['Refresh closed_dates or use an authoritative market-state source for holidays/halts.','Recheck near the order: earlier success does not stay valid indefinitely.','Independent workflows still require independent order guards.'],
+        'pitfalls':['For US regular-session requests set exchange_calendar=XNAS or XNYS on BOTH initial and final gates. Weekdays alone do not handle holidays or early closes.', 'Calendar rules do not observe live halts or new emergency closures; use a live market-state source when required.','Recheck near the order: earlier success does not stay valid indefinitely.','Independent workflows still require independent order guards.'],
     }
     _examples: ClassVar[list[dict[str, Any]]] = [
         {
@@ -113,10 +115,17 @@ class SessionGateNode(BaseNode):
     def get_field_schema(cls):
         from programgarden_core.models.field_binding import FieldSchema, FieldType, FieldCategory, ExpressionMode
         descriptions={name:cls.model_fields[name].description for name in ('timezone','windows','days','closed_dates')}
-        return {name:FieldSchema(name=name,type=kind,description=descriptions[name],required=name!='closed_dates',
+        fields = {name:FieldSchema(name=name,type=kind,description=descriptions[name],required=name!='closed_dates',
                 category=FieldCategory.PARAMETERS,expression_mode=ExpressionMode.FIXED_ONLY,
                 **({'array_item_type':FieldType.OBJECT if name=='windows' else FieldType.STRING} if kind==FieldType.ARRAY else {}))
                 for name,kind in [('timezone',FieldType.STRING),('windows',FieldType.ARRAY),('days',FieldType.ARRAY),('closed_dates',FieldType.ARRAY)]}
+        fields['exchange_calendar'] = FieldSchema(
+            name='exchange_calendar', type=FieldType.STRING,
+            description=cls.model_fields['exchange_calendar'].description, required=False,
+            enum_values=['XNYS', 'XNAS'], category=FieldCategory.PARAMETERS,
+            expression_mode=ExpressionMode.FIXED_ONLY,
+        )
+        return fields
 
     def evaluate_at(self, instant: datetime) -> dict[str, Any]:
         """Pure time decision; the executable node always supplies the real clock."""
@@ -134,8 +143,17 @@ class SessionGateNode(BaseNode):
             if inside and opening.weekday() in allowed_days and not {local.date().isoformat(),opening.isoformat()} & set(self.closed_dates):
                 matched=opening.isoformat()
                 break
+        reason = 'inside_configured_window' if matched else 'outside_configured_window'
+        if matched and self.exchange_calendar is not None:
+            from programgarden_core.market_calendar import scheduled_session_open
+            try:
+                if not scheduled_session_open(self.exchange_calendar, instant):
+                    matched, reason = None, 'outside_exchange_session'
+            except Exception:
+                # A broken/missing calendar must never fall back to weekdays.
+                matched, reason = None, 'calendar_unavailable'
         return {'allowed':matched is not None,'local_date':local.date().isoformat(),'session_date':matched or '',
-                'local_time':local.isoformat(),'reason':'inside_configured_window' if matched else 'outside_configured_window'}
+                'local_time':local.isoformat(),'reason':reason}
 
     async def execute(self, context: Any) -> dict[str, Any]:
         return self.evaluate_at(datetime.now(timezone.utc))

{programgarden_core-2.5.1 → programgarden_core-2.5.3}/pyproject.toml

@@ -5,7 +5,7 @@ authors = [
 homepage = "https://programgarden.com"
 requires-python = ">=3.12"
 name = "programgarden-core"
-version = "2.5.1"
+version = "2.5.3"
 license = "AGPL-3.0-or-later"
 description = "ProgramGarden Core - 노드 기반 DSL 핵심 타입 정의"
 readme = "README.md"
@@ -18,6 +18,7 @@ packages = [
 [tool.poetry.dependencies]
 pydantic = ">=2.0.1,<3.0.0"
 tzdata = "^2025.2"
+exchange-calendars = {version = "4.13.2", python = ">=3.12,<4.0"}
 
 [tool.poetry.group.dev.dependencies]
 pytest = "^8.0.0"