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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: programgarden-core
-Version: 2.5.0
+Version: 2.5.1
 Summary: ProgramGarden Core - 노드 기반 DSL 핵심 타입 정의
 License-Expression: AGPL-3.0-or-later
 Author: 프로그램동산

{programgarden_core-2.5.0 → programgarden_core-2.5.1}/programgarden_core/nodes/ai.py

@@ -43,13 +43,15 @@ class LLMModelNode(BaseNode):
     category: NodeCategory = NodeCategory.AI
 
     # 연결(자격증명) 선언 — 챗봇/편집기/검증기 공용. AI 모델 키는 실행에 반드시 필요하다.
+    # missing="ask" (오너 결정 2026-09-28): 키가 없으면 챗봇이 먼저 등록을 묻고, 사용자가
+    # "키 없이 진행" 이라고 명시할 때만 초안으로 저장한다("draft" 의 조용한 자동 초안과 구분).
     _connection: ClassVar[Dict[str, Any]] = {
         "purpose": "ai",
         "need": "run",
         "when": "always",
         "label_key": "connection.LLMModelNode.label",
         "presets": [],
-        "missing": "draft",
+        "missing": "ask",
     }
 
 
@@ -204,7 +206,7 @@ class LLMModelNode(BaseNode):
         },
     ]
     _node_guide: ClassVar[Dict[str, Any]] = {
-        "input_handling": "credential_id is mandatory and fixed (no expressions). It must reference a registered credential of kind llm_openai, llm_anthropic, llm_deepseek or llm_google whose api_key the user entered themselves; until the user registers and selects such a key the workflow can be built and saved but not run. Set model to the exact model ID for that provider. No data input is needed — this node only establishes the API connection.",
+        "input_handling": "credential_id is mandatory and fixed (no expressions). It must reference a registered credential of kind llm_openai, llm_anthropic, llm_deepseek or llm_google whose api_key the user entered themselves; until the user registers and selects such a key the workflow can be built and saved but not run. Because the key is required to run, the chatbot asks the user to register the AI-model key before building (connection.missing='ask'); it only saves a key-free draft when the user explicitly says to proceed without it. Set model to the exact model ID for that provider. No data input is needed — this node only establishes the API connection.",
         "output_consumption": "The 'connection' output port uses edge type 'ai_model', NOT 'main'. Connect it to AIAgentNode's ai_model input. The connection object is not a data value — it is an internal LLM client handle passed to the agent.",
         "common_combinations": [
             "LLMModelNode → AIAgentNode (ai_model edge) — always paired",
@@ -234,9 +236,11 @@ class LLMModelNode(BaseNode):
         ),
     ]
 
-    _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-09-28"
+    _change_note: ClassVar[Optional[str]] = (
+        "connection.missing='ask' — chatbot asks the user to register the AI-model key before build"
+    )
 
     @classmethod
     def is_tool_enabled(cls) -> bool:

{programgarden_core-2.5.0 → programgarden_core-2.5.1}/programgarden_core/nodes/data.py

@@ -13,7 +13,7 @@ MarketDataNode는 상품별 분리됨:
 계좌 조회는 account_stock/account_futures 참조
 """
 
-from typing import Optional, List, Literal, Dict, Any, ClassVar, TYPE_CHECKING
+from typing import Optional, List, Literal, Dict, Any, ClassVar, Tuple, TYPE_CHECKING
 from pydantic import Field
 
 if TYPE_CHECKING:
@@ -47,8 +47,15 @@ class HTTPServerError(Exception):
 
 
 class HTTPRateLimitError(Exception):
-    """HTTP 429 Rate Limit 에러 - 재시도 가능"""
-    pass
+    """HTTP 429 Rate Limit 에러 - 재시도 가능.
+
+    `Retry-After` 헤더가 있으면 그 값을 `retry_after`(초, float)에 실어 RetryExecutor 가
+    지수 백오프 대신(또는 그와 함께) 서버가 요구한 대기 시간을 존중하게 한다.
+    """
+
+    def __init__(self, message: str, retry_after: Optional[float] = None):
+        super().__init__(message)
+        self.retry_after = retry_after
 
 
 class HTTPNetworkError(Exception):
@@ -61,6 +68,72 @@ class HTTPTimeoutError(Exception):
     pass
 
 
+class HTTPCredentialError(Exception):
+    """An authenticated HTTP node has no injected credential; no request was sent."""
+
+
+# ── HTTP 외부 API 보호 (오너 우려 2026-09-28: 클라우드 공유 IP 로 종목마다 요청이 동시에
+#    나가면 외부 API 사가 차단할 수 있다) ─────────────────────────────────────────────
+# 호스트별 동시 요청 상한. auto-iterate 반복은 원래 순차 실행 + rate_limit_interval 간격이라
+# 안전하지만, 실시간/병렬(fan-out) 경로에서 같은 호스트로 요청이 몰리는 것을 막는 프로세스
+# 전역 가드다. 기본 1 = 한 호스트에 한 번에 한 요청. 상수는 여기 한 곳에서만 정의한다.
+HTTP_MAX_CONCURRENCY_PER_HOST: int = 1
+
+# (event-loop id, host) → Semaphore. asyncio.Semaphore 는 생성된 이벤트 루프에 묶이므로
+# 루프별로 따로 만든다(워커는 보통 루프 하나지만, 다른 루프에서 재사용 시 RuntimeError 회피).
+_HOST_SEMAPHORES: Dict[Tuple[int, str], "object"] = {}
+
+
+def _host_semaphore(url: str):
+    """이 URL 호스트의 프로세스 전역 동시성 세마포어(현재 이벤트 루프 기준)."""
+    import asyncio
+    from urllib.parse import urlparse
+
+    try:
+        host = (urlparse(url).hostname or "").lower()
+    except Exception:
+        host = ""
+    try:
+        loop_id = id(asyncio.get_running_loop())
+    except RuntimeError:
+        loop_id = 0
+    key = (loop_id, host)
+    sem = _HOST_SEMAPHORES.get(key)
+    if sem is None:
+        sem = asyncio.Semaphore(HTTP_MAX_CONCURRENCY_PER_HOST)
+        _HOST_SEMAPHORES[key] = sem
+    return sem
+
+
+def _parse_retry_after(value: Optional[str]) -> Optional[float]:
+    """HTTP `Retry-After` 헤더 → 대기 초. delta-seconds(정수) 또는 HTTP-date 지원.
+
+    음수/파싱 실패는 None (그러면 RetryExecutor 가 순수 지수 백오프로 되돌아간다).
+    """
+    if not value:
+        return None
+    value = value.strip()
+    # delta-seconds (가장 흔한 형태)
+    try:
+        secs = float(value)
+        return secs if secs >= 0 else None
+    except (TypeError, ValueError):
+        pass
+    # HTTP-date (RFC 7231)
+    try:
+        from email.utils import parsedate_to_datetime
+        from datetime import datetime, timezone
+
+        dt = parsedate_to_datetime(value)
+        if dt is None:
+            return None
+        if dt.tzinfo is None:
+            dt = dt.replace(tzinfo=timezone.utc)
+        return max(0.0, (dt - datetime.now(timezone.utc)).total_seconds())
+    except Exception:
+        return None
+
+
 class SQLiteNode(BaseNode):
     """
     로컬 SQLite 데이터베이스 노드 (단순 DB)
@@ -584,6 +657,10 @@ class HTTPRequestNode(BaseNode):
         default=None, 
         description="Credential ID (credentials 섹션에서 참조)"
     )
+    credential_preset: Optional[Literal["fmp", "finnhub"]] = Field(
+        default=None,
+        description="Non-secret provider preset for the credential registration form; never selects a stored key.",
+    )
 
     # === Headers: UI에서 동적 추가 ===
     headers: Optional[Dict[str, str]] = Field(default=None, description="HTTP headers")
@@ -628,7 +705,8 @@ class HTTPRequestNode(BaseNode):
     }
     _features: ClassVar[List[str]] = [
         "Supports all HTTP methods: GET, POST, PUT, PATCH, DELETE with optional query params and request body",
-        "Built-in resilience: retry on 5xx and 429 with exponential backoff (enabled by default, max_retries=3)",
+        "Built-in resilience: retry on 5xx and 429 with exponential backoff (enabled by default, max_retries=3). Retry-After is a minimum wait. When it exceeds max_delay or the 5-second validation wait budget, retrying stops with the original failure; the server's wait is never shortened. Existing fallback and per-item error handling apply.",
+        "Per-host concurrency cap (default 1): the engine lets only one request per host run at a time process-wide, so many parallel/fan-out requests to the same external API (shared cloud egress IP) queue instead of stampeding. Auto-iterate is already sequential and paced by rate_limit_interval.",
         "Credential integration for Bearer token, HTTP Basic, custom header, and query-param auth patterns",
         "Rate-limited: minimum 1-second interval and max 3 concurrent calls; real-time node connections blocked",
         "is_tool_enabled=True — AI Agent can invoke HTTPRequestNode as a tool to fetch live external data",
@@ -767,11 +845,10 @@ class HTTPRequestNode(BaseNode):
 
     _field_schema: ClassVar[Dict[str, "FieldSchema"]] = {}
 
-    _version: ClassVar[str] = "1.1.0"
+    _version: ClassVar[str] = "1.2.0"
     _updated_at: ClassVar[str] = "2026-09-28"
     _change_note: ClassVar[Optional[str]] = (
-        "Added `results` port: one entry per iterated item ({{ item }} refs); "
-        "scalar ports keep the last item's value."
+        "429 honours Retry-After + per-host concurrency cap (1) for shared-IP safety"
     )
 
     @classmethod
@@ -832,6 +909,14 @@ class HTTPRequestNode(BaseNode):
                 credential_types=["http_bearer", "http_header", "http_basic", "http_query"],
                 ui_component=UIComponent.CUSTOM_CREDENTIAL_SELECT,
             ),
+            "credential_preset": FieldSchema(
+                name="credential_preset", type=FieldType.ENUM, required=False,
+                description="Non-secret provider preset for credential registration",
+                category=FieldCategory.PARAMETERS,
+                expression_mode=ExpressionMode.FIXED_ONLY,
+                enum_values=[p["id"] for p in cls._connection["presets"]],
+                group="advanced",
+            ),
             "headers": FieldSchema(
                 name="headers", type=FieldType.KEY_VALUE_PAIRS, required=False,
                 description="i18n:fields.HTTPRequestNode.headers",
@@ -933,6 +1018,16 @@ class HTTPRequestNode(BaseNode):
         - 5xx 서버 에러, 네트워크 에러, 타임아웃 → Exception raise → 재시도
         - 4xx 클라이언트 에러 → 재시도 불가, 결과 반환
         """
+        if self.auth_required is True and not (
+            getattr(self, "token", None)
+            or (getattr(self, "header_name", None) and getattr(self, "header_value", None))
+            or (getattr(self, "username", None) and getattr(self, "password", None))
+            or (getattr(self, "param_name", None) and getattr(self, "param_value", None))
+        ):
+            raise HTTPCredentialError(
+                "CREDENTIAL_REQUIRED_TO_RUN: register and bind this HTTP node's API credential"
+            )
+
         import aiohttp
         import asyncio
         import json
@@ -986,41 +1081,49 @@ class HTTPRequestNode(BaseNode):
                     else:
                         request_kwargs["data"] = self.body
 
-                async with session.request(**request_kwargs) as resp:
-                    status_code = resp.status
-
-                    # 응답 파싱 (JSON 시도 → 실패하면 text)
-                    try:
-                        data = await resp.json()
-                    except Exception:
-                        data = await resp.text()
-
-                    # 5xx 서버 에러 → Exception raise (RetryExecutor가 재시도)
-                    if status_code >= 500:
-                        error_msg = data if isinstance(data, str) else json.dumps(data, ensure_ascii=False)[:200]
-                        raise HTTPServerError(f"HTTP {status_code}: {error_msg}")
-
-                    # 429 Rate Limit → Exception raise (RetryExecutor가 재시도)
-                    if status_code == 429:
-                        raise HTTPRateLimitError(f"HTTP 429: Rate limit exceeded")
-
-                    # 4xx 클라이언트 에러 → 재시도 불가, 결과 반환
-                    if status_code >= 400:
-                        return {
-                            "response": data,
-                            "status_code": status_code,
-                            "success": False,
-                            "error": f"HTTP {status_code}",
-                        }
-
-                    # 성공 (2xx, 3xx)
+                # 호스트별 동시성 상한(기본 1) — 같은 호스트로 요청이 병렬로 몰리는 것을
+                # 프로세스 전역에서 막는다(공유 IP 보호). 반복은 어차피 순차라 무영향.
+                async with _host_semaphore(self.url):
+                    async with session.request(**request_kwargs) as resp:
+                        status_code = resp.status
+                        # Retry-After 는 응답 컨텍스트를 벗어나기 전에 읽어둔다.
+                        retry_after = _parse_retry_after(resp.headers.get("Retry-After"))
+
+                        # 응답 파싱 (JSON 시도 → 실패하면 text)
+                        try:
+                            data = await resp.json()
+                        except Exception:
+                            data = await resp.text()
+
+                # 5xx 서버 에러 → Exception raise (RetryExecutor가 재시도)
+                if status_code >= 500:
+                    error_msg = data if isinstance(data, str) else json.dumps(data, ensure_ascii=False)[:200]
+                    raise HTTPServerError(f"HTTP {status_code}: {error_msg}")
+
+                # 429 Rate Limit → Exception raise (RetryExecutor가 지수 백오프 재시도).
+                # Retry-After 헤더가 있으면 그 대기 시간을 예외에 실어 존중하게 한다.
+                if status_code == 429:
+                    raise HTTPRateLimitError(
+                        "HTTP 429: Rate limit exceeded", retry_after=retry_after
+                    )
+
+                # 4xx 클라이언트 에러 → 재시도 불가, 결과 반환
+                if status_code >= 400:
                     return {
                         "response": data,
                         "status_code": status_code,
-                        "success": True,
-                        "error": None,
+                        "success": False,
+                        "error": f"HTTP {status_code}",
                     }
 
+                # 성공 (2xx, 3xx)
+                return {
+                    "response": data,
+                    "status_code": status_code,
+                    "success": True,
+                    "error": None,
+                }
+
         except aiohttp.ClientError as e:
             # 네트워크 에러 → RetryExecutor가 재시도
             raise HTTPNetworkError(f"Network error: {e}")

{programgarden_core-2.5.0 → programgarden_core-2.5.1}/programgarden_core/nodes/trigger.py

@@ -74,6 +74,22 @@ class ScheduleNode(BaseNode):
             "investor named a fixed number of cycles (>= 1)."
         ),
     )
+    # Owner concern 2026-09-28: many workflows sharing one cron instant (e.g.
+    # "0 9 * * *") all fire at the same second and stampede a shared cloud
+    # egress IP. jitter_seconds staggers the ACTUAL fire by a random 0..jitter
+    # seconds past each cron instant. 0 (default) = fire exactly on the instant
+    # (unchanged). Max 300s. dry_run never applies jitter (it emits one tick and
+    # exits), so it does not affect the build budget or replay semantics.
+    jitter_seconds: int = Field(
+        default=0,
+        ge=0,
+        le=300,
+        description=(
+            "Random 0..N second delay applied to each fire past the cron instant, "
+            "to spread many same-cron workflows across a shared egress IP. "
+            "0 (default) fires exactly on the cron instant; max 300."
+        ),
+    )
 
     _inputs: List[InputPort] = []
     _outputs: List[OutputPort] = [
@@ -106,6 +122,7 @@ class ScheduleNode(BaseNode):
         "Standard 5-field cron expression — minute / hour / day / month / weekday",
         "Timezone-aware (IANA names) — 'America/New_York', 'Asia/Seoul', 'UTC'",
         "max_duration_hours and count are optional bounds: omit both and the schedule runs until the workflow is stopped; set one and the scheduler exits cleanly at that limit",
+        "jitter_seconds (optional, 0..300, default 0) delays each fire by a random 0..N seconds past the cron instant, so many workflows sharing one cron ('0 9 * * *') do not all hit a shared egress IP at the same second; the cron cadence anchor is unchanged and the logical replay instant is not affected. Keep jitter well below the interval (do not set 300s jitter on an every-minute cron).",
         "enabled=False freezes the trigger without removing the node from the DAG",
         "A tick re-executes the whole main flow: the ScheduleNode returns {trigger: true} without re-registering, so every node downstream of it runs again on each tick",
         "Startup account and open-order snapshots are not retained across schedule ticks; they are retained only across realtime events",
@@ -189,7 +206,7 @@ class ScheduleNode(BaseNode):
         },
     ]
     _node_guide: ClassVar[Dict[str, Any]] = {
-        "input_handling": "No data inputs. All behavior is configured via `cron`, `timezone`, `enabled`, and the optional bounds `max_duration_hours` / `count` (omit both to run until the workflow is stopped).",
+        "input_handling": "No data inputs. All behavior is configured via `cron`, `timezone`, `enabled`, the optional bounds `max_duration_hours` / `count` (omit both to run until the workflow is stopped), and the optional `jitter_seconds` (0..300, default 0) which staggers each fire a random 0..N seconds past the cron instant to avoid a shared-IP stampede.",
         "output_consumption": "`trigger` output carries `{fired_at, cycle_index}`. Downstream nodes usually just need an incoming edge; explicit binding is optional.",
         "common_combinations": [
             "StartNode → ScheduleNode → trading body (plain cron workflow)",
@@ -203,9 +220,11 @@ class ScheduleNode(BaseNode):
         ],
     }
 
-    _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-09-28"
+    _change_note: ClassVar[Optional[str]] = (
+        "Added optional jitter_seconds (0..300) to stagger fires past the cron instant"
+    )
 
     @classmethod
     def get_field_schema(cls) -> Dict[str, "FieldSchema"]:
@@ -271,6 +290,18 @@ class ScheduleNode(BaseNode):
                 expected_type="int",
                 example=1000,
             ),
+            "jitter_seconds": FieldSchema(
+                name="jitter_seconds",
+                type=FieldType.INTEGER,
+                description="Random 0..N second delay applied to each fire past the cron instant, to spread many same-cron workflows across a shared egress IP. 0 (default) fires exactly on the cron instant; max 300.",
+                default=0,
+                min_value=0,
+                max_value=300,
+                expression_mode=ExpressionMode.FIXED_ONLY,
+                category=FieldCategory.SETTINGS,
+                expected_type="int",
+                example=30,
+            ),
         }
 
 

{programgarden_core-2.5.0 → programgarden_core-2.5.1}/programgarden_core/registry/node_registry.py

@@ -129,7 +129,10 @@ class NodeTypeSchema(BaseModel):
             "when the node config marks the API authenticated), label_ko, "
             "label_en (plain user-facing names), presets (HTTPRequestNode only; "
             "[] elsewhere), missing (draft = may be saved without it and the run "
-            "gate blocks; block = must exist before build)."
+            "gate blocks; block = must exist before build; ask = the chatbot "
+            "must ask the user to register the credential and only drafts "
+            "without it when the user explicitly says to proceed without it — "
+            "owner decision 2026-09-28 for AI-model keys and the Telegram bot)."
         ),
     )
 
@@ -496,7 +499,7 @@ class NodeTypeRegistry:
     _CONNECTION_PURPOSES = ("trading", "data", "ai", "notify")
     _CONNECTION_NEEDS = ("run", "validate", "optional")
     _CONNECTION_WHENS = ("always", "auth_required", "never")
-    _CONNECTION_MISSINGS = ("draft", "block")
+    _CONNECTION_MISSINGS = ("draft", "block", "ask")
 
     def _build_connection(
         self, node_class: Type[BaseNode], config_schema: Dict[str, Any],

{programgarden_core-2.5.0 → programgarden_core-2.5.1}/programgarden_core/retry_executor.py

@@ -34,6 +34,10 @@ if TYPE_CHECKING:
 
 logger = logging.getLogger("programgarden.retry_executor")
 
+# Validation has a bounded wait budget. If Retry-After exceeds it, stop this
+# retry sequence and preserve the failure instead of contacting the API early.
+DRY_RUN_MAX_RETRY_WAIT_SEC: float = 5.0
+
 
 class RetryExecutor:
     """
@@ -106,12 +110,23 @@ class RetryExecutor:
                     )
                     break
 
-                # 대기 시간 계산 (exponential backoff with jitter)
-                delay = self._calculate_delay(config.retry, attempt)
+                # A server-directed wait is a floor, never a delay to truncate.
+                retry_after = getattr(e, "retry_after", None)
+                dry_run = bool(getattr(context, "is_dry_run", False))
+                delay = self._calculate_delay(
+                    config.retry, attempt, retry_after=retry_after, dry_run=dry_run
+                )
+                if delay is None:
+                    logger.warning(
+                        "[%s] Retry-After exceeds the retry wait budget; no further attempt",
+                        node.id,
+                    )
+                    break
 
                 logger.info(
                     f"[{node.id}] {error_type.value} 발생, "
                     f"재시도 {attempt}/{config.retry.max_retries}... {delay:.1f}초 후"
+                    + (f" (Retry-After={retry_after:.0f}s)" if retry_after else "")
                 )
 
                 # 재시도 이벤트 발송 (context.notify_retry 사용)
@@ -143,13 +158,14 @@ class RetryExecutor:
                     category=NotificationCategory.RETRY_EXHAUSTED,
                     severity=NotificationSeverity.WARNING,
                     title=f"Retry exhausted: {node.id}",
-                    message=f"{node.__class__.__name__} failed after {config.retry.max_retries} retries: {last_error}",
+                    message=f"{node.__class__.__name__} failed after {attempt} attempts: {last_error}",
                     node_id=node.id,
                     node_type=node.__class__.__name__,
                     data={
                         "node_id": node.id,
                         "node_type": node.__class__.__name__,
                         "max_retries": config.retry.max_retries,
+                        "attempts": attempt,
                         "last_error": str(last_error),
                     },
                 )
@@ -159,16 +175,19 @@ class RetryExecutor:
         # Fallback 처리
         return self._handle_fallback(node, last_error, config.fallback)
 
-    def _calculate_delay(self, config: RetryConfig, attempt: int) -> float:
+    def _calculate_delay(
+        self,
+        config: RetryConfig,
+        attempt: int,
+        retry_after: Optional[float] = None,
+        dry_run: bool = False,
+    ) -> Optional[float]:
         """
-        대기 시간 계산 (exponential backoff with jitter).
-
-        Args:
-            config: RetryConfig
-            attempt: 현재 시도 횟수 (1부터 시작)
+        Return bounded exponential backoff with the server's minimum wait.
 
-        Returns:
-            대기 시간 (초)
+        None means Retry-After cannot fit the configured wait budget: callers
+        must end the retry sequence, retaining the original failure. Ordinary
+        backoff remains capped when no server-directed floor prevents a retry.
         """
         if config.exponential_backoff:
             # 2^(attempt-1) * base_delay
@@ -183,8 +202,10 @@ class RetryExecutor:
         jitter = delay * 0.25 * (random.random() * 2 - 1)
         delay = delay + jitter
 
-        # max_delay 제한
-        return min(delay, config.max_delay)
+        limit = min(config.max_delay, DRY_RUN_MAX_RETRY_WAIT_SEC) if dry_run else config.max_delay
+        if retry_after is not None and retry_after > limit:
+            return None
+        return max(min(delay, limit), retry_after or 0.0)
 
     def _handle_fallback(
         self,

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

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