programgarden-core 1.12.2__tar.gz → 1.12.4__tar.gz

{programgarden_core-1.12.2 → programgarden_core-1.12.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: programgarden-core
-Version: 1.12.2
+Version: 1.12.4
 Summary: ProgramGarden Core - 노드 기반 DSL 핵심 타입 정의
 Author: 프로그램동산
 Author-email: coding@programgarden.com

{programgarden_core-1.12.2 → programgarden_core-1.12.4}/programgarden_core/__init__.py

@@ -24,7 +24,7 @@ from programgarden_core.exceptions import *
 from programgarden_core import korea_alias
 from programgarden_core import bases
 
-__version__ = "2.0.0"
+__version__ = "1.12.4"
 __all__ = [
     # Nodes - Base
     "BaseNode",
@@ -96,6 +96,20 @@ __all__ = [
     "JobState",
     "BrokerCredential",
     "Event",
+    # Validation (structured errors + recommendations)
+    "ErrorSeverity",
+    "ErrorCode",
+    "ErrorLocation",
+    "ErrorInfo",
+    "RecommendationCategory",
+    "Recommendation",
+    "ValidationLimits",
+    "ResultSummary",
+    "ValidationResult",
+    "CASCADE_SUPPRESSION_RULES",
+    "default_severity_for",
+    "suggest_close_match",
+    "build_error",
     # Registry
     "NodeTypeRegistry",
     "PluginRegistry",

{programgarden_core-1.12.2 → programgarden_core-1.12.4}/programgarden_core/models/__init__.py

@@ -78,6 +78,21 @@ from programgarden_core.models.connection_rule import (
     ConnectionRule,
     RateLimitConfig,
 )
+from programgarden_core.models.validation import (
+    ErrorSeverity,
+    ErrorCode,
+    ErrorLocation,
+    ErrorInfo,
+    RecommendationCategory,
+    Recommendation,
+    ValidationLimits,
+    ResultSummary,
+    ValidationResult,
+    CASCADE_SUPPRESSION_RULES,
+    default_severity_for,
+    suggest_close_match,
+    build_error,
+)
 
 __all__ = [
     # Edge
@@ -150,4 +165,18 @@ __all__ = [
     "ConnectionSeverity",
     "ConnectionRule",
     "RateLimitConfig",
+    # Validation
+    "ErrorSeverity",
+    "ErrorCode",
+    "ErrorLocation",
+    "ErrorInfo",
+    "RecommendationCategory",
+    "Recommendation",
+    "ValidationLimits",
+    "ResultSummary",
+    "ValidationResult",
+    "CASCADE_SUPPRESSION_RULES",
+    "default_severity_for",
+    "suggest_close_match",
+    "build_error",
 ]

programgarden_core-1.12.4/programgarden_core/models/validation.py

@@ -0,0 +1,329 @@
+"""Structured validation errors for AI-chatbot-friendly workflow validation.
+
+ErrorInfo objects let downstream consumers (AI chatbots, IDEs, dashboards)
+make deterministic self-correction decisions based on error codes and
+structured location metadata instead of parsing free-form strings.
+
+All user-facing strings in this module (and all consumers) must be English.
+"""
+from __future__ import annotations
+
+from difflib import get_close_matches
+from enum import Enum
+from typing import Any, Dict, Iterable, List, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ErrorSeverity(str, Enum):
+    ERROR = "error"
+    WARNING = "warning"
+
+
+class ErrorCode(str, Enum):
+    # Definition / structure
+    DEFINITION_PARSE_ERROR = "DEFINITION_PARSE_ERROR"
+    DUPLICATE_NODE_ID = "DUPLICATE_NODE_ID"
+    RESERVED_NODE_ID = "RESERVED_NODE_ID"
+    MISSING_START_NODE = "MISSING_START_NODE"
+    MULTIPLE_START_NODES = "MULTIPLE_START_NODES"
+    CYCLE_DETECTED = "CYCLE_DETECTED"
+
+    # Node / plugin registry
+    UNKNOWN_NODE_TYPE = "UNKNOWN_NODE_TYPE"
+    UNKNOWN_DYNAMIC_NODE_SCHEMA = "UNKNOWN_DYNAMIC_NODE_SCHEMA"
+    DYNAMIC_NODE_CREDENTIAL_FORBIDDEN = "DYNAMIC_NODE_CREDENTIAL_FORBIDDEN"
+    DYNAMIC_NODE_CLASS_NOT_INJECTED = "DYNAMIC_NODE_CLASS_NOT_INJECTED"
+    MISSING_PLUGIN = "MISSING_PLUGIN"
+    UNKNOWN_PLUGIN = "UNKNOWN_PLUGIN"
+
+    # Edges
+    INVALID_EDGE_REF = "INVALID_EDGE_REF"
+    INVALID_EDGE_PORT = "INVALID_EDGE_PORT"
+    INVALID_AI_MODEL_EDGE = "INVALID_AI_MODEL_EDGE"
+    INVALID_TOOL_EDGE = "INVALID_TOOL_EDGE"
+
+    # Expressions / fields
+    INVALID_EXPRESSION_REF = "INVALID_EXPRESSION_REF"
+    INVALID_EXPRESSION_SYNTAX = "INVALID_EXPRESSION_SYNTAX"
+    MISSING_REQUIRED_FIELD = "MISSING_REQUIRED_FIELD"
+    INVALID_FIELD_TYPE = "INVALID_FIELD_TYPE"
+    INVALID_FIELD_ENUM = "INVALID_FIELD_ENUM"
+
+    # Credentials
+    UNKNOWN_CREDENTIAL = "UNKNOWN_CREDENTIAL"
+
+    # Broker / connection rules
+    DUPLICATE_BROKER_NODE = "DUPLICATE_BROKER_NODE"
+    MISSING_REQUIRED_BROKER = "MISSING_REQUIRED_BROKER"
+    INCOMPATIBLE_BROKER_PROVIDER = "INCOMPATIBLE_BROKER_PROVIDER"
+    CONNECTION_RULE_VIOLATION = "CONNECTION_RULE_VIOLATION"
+
+    # Runtime (dry_run)
+    DRY_RUN_RUNTIME_ERROR = "DRY_RUN_RUNTIME_ERROR"
+    DRY_RUN_CREDENTIAL_MISSING = "DRY_RUN_CREDENTIAL_MISSING"
+    DRY_RUN_DEPENDENCY_FAILURE = "DRY_RUN_DEPENDENCY_FAILURE"
+
+
+_DEFAULT_SEVERITY: Dict[ErrorCode, ErrorSeverity] = {
+    ErrorCode.UNKNOWN_PLUGIN: ErrorSeverity.WARNING,
+}
+
+
+def default_severity_for(code: ErrorCode) -> ErrorSeverity:
+    return _DEFAULT_SEVERITY.get(code, ErrorSeverity.ERROR)
+
+
+class ErrorLocation(BaseModel):
+    """Where in the workflow definition the error occurred. All fields optional."""
+
+    node_id: Optional[str] = Field(default=None, description="Node id from definition.nodes[].id")
+    node_type: Optional[str] = Field(default=None, description="Node type (e.g. 'OverseasStockNewOrderNode')")
+    field_path: Optional[str] = Field(default=None, description="Dot/bracket notation: 'fields.period' or 'symbols[0].symbol'")
+    edge_index: Optional[int] = Field(default=None, description="Index into definition.edges[]")
+    edge_from: Optional[str] = Field(default=None, description="Edge.from raw value (may include dot port)")
+    edge_to: Optional[str] = Field(default=None, description="Edge.to raw value")
+    credential_id: Optional[str] = Field(default=None, description="Credential id from definition.credentials[]")
+    plugin_id: Optional[str] = Field(default=None, description="Plugin id referenced by ConditionNode etc.")
+    expression: Optional[str] = Field(default=None, description="Raw expression string when INVALID_EXPRESSION_*")
+    output_port: Optional[str] = Field(default=None, description="Output port name on source node")
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class RecommendationCategory(str, Enum):
+    DATA_FLOW = "data_flow"
+    RESILIENCE = "resilience"
+    PERFORMANCE = "performance"
+    SAFETY = "safety"
+    READABILITY = "readability"
+
+
+class Recommendation(BaseModel):
+    """Non-blocking quality-improvement hint for AI chatbots and users.
+
+    Recommendations are deterministic, rule-based suggestions — never prescribe
+    a single fixed value. Always present options with rationale so the
+    consumer (chatbot or human) can pick the right one for their context.
+
+    `example_snippet` is a partial workflow fragment (one or two
+    nodes/edges) showing one applied option — not a full workflow JSON. The
+    chatbot is expected to merge it into the user's existing workflow.
+    """
+    title: str = Field(description="Short one-line hint (English). Use 'Consider X' tone.")
+    rationale: str = Field(description="Why this may improve the workflow — 1~2 sentences.")
+    category: RecommendationCategory
+    location: Optional[ErrorLocation] = Field(default=None, description="Optional anchor point in the workflow")
+    options: List[str] = Field(default_factory=list, description="2+ alternative approaches the user/AI may pick from")
+    example_snippet: Optional[Dict[str, Any]] = Field(
+        default=None,
+        description="Partial workflow JSON showing one applied option (node/edge fragment only — not a full workflow)",
+    )
+    rule_id: str = Field(description="Deterministic rule identifier for testing / suppression (e.g. 'REC_REALTIME_THROTTLE')")
+
+    model_config = ConfigDict(use_enum_values=True)
+
+    def short(self) -> str:
+        return f"[{self.rule_id}] {self.title} — {self.rationale}"
+
+
+class ErrorInfo(BaseModel):
+    code: ErrorCode
+    severity: ErrorSeverity = Field(default=ErrorSeverity.ERROR)
+    location: ErrorLocation = Field(default_factory=ErrorLocation)
+    message: str = Field(description="Human-readable English message. One sentence preferred.")
+    suggestion: Optional[str] = Field(default=None, description="Single-line English remediation hint.")
+    available_values: Optional[List[str]] = Field(
+        default=None,
+        description="Closest valid candidates for enum/registry-style errors (suggest_close_match result).",
+    )
+    docs_url: Optional[str] = Field(default=None, description="Optional anchor link to documentation.")
+    details: Dict[str, Any] = Field(default_factory=dict, description="Free-form structured context.")
+    recommendations: List[Recommendation] = Field(
+        default_factory=list,
+        description="Optional improvement hints worth considering while fixing this error.",
+    )
+
+    model_config = ConfigDict(use_enum_values=True)
+
+    def short(self) -> str:
+        loc_parts: List[str] = []
+        if self.location.node_id:
+            loc_parts.append(f"node={self.location.node_id}")
+        if self.location.field_path:
+            loc_parts.append(f"field={self.location.field_path}")
+        if self.location.edge_index is not None:
+            loc_parts.append(f"edge[{self.location.edge_index}]")
+        suffix = f" ({', '.join(loc_parts)})" if loc_parts else ""
+        return f"[{self.code}] {self.message}{suffix}"
+
+
+class ValidationLimits(BaseModel):
+    """Output volume limits to prevent overwhelming LLM context."""
+
+    max_errors: int = Field(default=20, ge=1)
+    max_warnings: int = Field(default=10, ge=1)
+    max_recommendations_per_channel: int = Field(default=10, ge=1)
+    max_per_node: int = Field(default=3, ge=1)
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class ResultSummary(BaseModel):
+    """Top-level summary for fast LLM triage of a ValidationResult."""
+
+    is_valid: bool
+    error_count: int = 0
+    warning_count: int = 0
+    static_recommendation_count: int = 0
+    runtime_recommendation_count: int = 0
+    critical_codes: List[ErrorCode] = Field(
+        default_factory=list,
+        description="Up to 3 most-impactful codes (cascade roots first, then frequency).",
+    )
+    root_cause_node_ids: List[str] = Field(
+        default_factory=list,
+        description="Node ids that triggered cascade suppression (fix these first).",
+    )
+    next_action_hint: Optional[str] = Field(
+        default=None,
+        description="Deterministic English single-line hint for the consumer's next step.",
+    )
+    truncated: bool = Field(
+        default=False,
+        description="True if any channel hit ValidationLimits and entries were dropped.",
+    )
+
+    model_config = ConfigDict(use_enum_values=True)
+
+
+class ValidationResult(BaseModel):
+    """Structured validation outcome for a workflow definition.
+
+    Two recommendation channels exist:
+    - `static_recommendations`: filled by `executor.validate()` (topology
+      analysis only)
+    - `runtime_recommendations`: filled by `executor.execute(dry_run=True)`
+      based on actual node mock outputs (e.g. REC_EMPTY_SYMBOL_LIST)
+    """
+
+    errors: List[ErrorInfo] = Field(default_factory=list)
+    warnings: List[ErrorInfo] = Field(default_factory=list)
+    static_recommendations: List[Recommendation] = Field(default_factory=list)
+    runtime_recommendations: List[Recommendation] = Field(default_factory=list)
+    summary: Optional[ResultSummary] = Field(
+        default=None,
+        description="Populated after post-processing (cascade suppression + capping). None until finalize() runs.",
+    )
+    truncated: Dict[str, int] = Field(
+        default_factory=dict,
+        description="Per-channel count of entries dropped by ValidationLimits (e.g. {'errors': 5}).",
+    )
+
+    model_config = ConfigDict(use_enum_values=True)
+
+    @property
+    def is_valid(self) -> bool:
+        return not self.errors
+
+    def add(self, info: ErrorInfo) -> None:
+        """Append an ErrorInfo into errors/warnings by severity."""
+        if info.severity == ErrorSeverity.WARNING or info.severity == ErrorSeverity.WARNING.value:
+            self.warnings.append(info)
+        else:
+            self.errors.append(info)
+
+    def add_static_recommendation(self, rec: Recommendation) -> None:
+        self.static_recommendations.append(rec)
+
+    def add_runtime_recommendation(self, rec: Recommendation) -> None:
+        self.runtime_recommendations.append(rec)
+
+    def all_recommendations(self) -> List[Recommendation]:
+        """Merge static + runtime channels (read-only helper for consumers that don't distinguish stages)."""
+        return [*self.static_recommendations, *self.runtime_recommendations]
+
+    def as_strings(self) -> List[str]:
+        """Human-readable one-line per entry. Not a legacy compat shim — English-only."""
+        lines: List[str] = []
+        lines.extend(e.short() for e in self.errors)
+        lines.extend(w.short() for w in self.warnings)
+        lines.extend(r.short() for r in self.all_recommendations())
+        return lines
+
+
+def suggest_close_match(
+    value: str,
+    candidates: Iterable[str],
+    cutoff: float = 0.6,
+    n: int = 3,
+) -> Optional[List[str]]:
+    """Return up to `n` closest matches above `cutoff`, or None if there are no matches.
+
+    Thin wrapper over `difflib.get_close_matches` with standardised defaults
+    for ErrorInfo.available_values.
+    """
+    matches = get_close_matches(value, list(candidates), n=n, cutoff=cutoff)
+    return matches or None
+
+
+def build_error(
+    code: ErrorCode,
+    message: str,
+    *,
+    location: Optional[ErrorLocation] = None,
+    suggestion: Optional[str] = None,
+    available_values: Optional[List[str]] = None,
+    details: Optional[Dict[str, Any]] = None,
+    severity: Optional[ErrorSeverity] = None,
+    recommendations: Optional[List[Recommendation]] = None,
+) -> ErrorInfo:
+    """DRY helper for resolver.py and dry_run capture sites."""
+    return ErrorInfo(
+        code=code,
+        severity=severity or default_severity_for(code),
+        location=location or ErrorLocation(),
+        message=message,
+        suggestion=suggestion,
+        available_values=available_values,
+        details=details or {},
+        recommendations=recommendations or [],
+    )
+
+
+# Cascade suppression rule data — actual application lives in Phase 4 post-processing.
+# Each entry documents which subordinate error codes a given root cause hides.
+CASCADE_SUPPRESSION_RULES: Dict[ErrorCode, str] = {
+    ErrorCode.UNKNOWN_NODE_TYPE: (
+        "Suppresses INVALID_EXPRESSION_REF / INVALID_EDGE_REF / INVALID_EDGE_PORT "
+        "where the source/target is the unknown node id."
+    ),
+    ErrorCode.MISSING_REQUIRED_BROKER: (
+        "Suppresses additional MISSING_REQUIRED_BROKER entries with the same "
+        "product_scope (keeps only the first)."
+    ),
+    ErrorCode.CYCLE_DETECTED: (
+        "Suppresses any follow-on validation errors on nodes inside the cycle."
+    ),
+    ErrorCode.DUPLICATE_NODE_ID: (
+        "Suppresses INVALID_EDGE_REF / INVALID_EXPRESSION_REF that reference the "
+        "duplicated id (since id resolution is ambiguous)."
+    ),
+}
+
+
+__all__ = [
+    "ErrorSeverity",
+    "ErrorCode",
+    "ErrorLocation",
+    "ErrorInfo",
+    "RecommendationCategory",
+    "Recommendation",
+    "ValidationLimits",
+    "ResultSummary",
+    "ValidationResult",
+    "CASCADE_SUPPRESSION_RULES",
+    "default_severity_for",
+    "suggest_close_match",
+    "build_error",
+]

{programgarden_core-1.12.2 → programgarden_core-1.12.4}/programgarden_core/models/workflow.py

@@ -206,42 +206,109 @@ class WorkflowDefinition(BaseModel):
             if node.get("id") not in nodes_with_input
         ]
 
-    def validate_structure(self) -> List[str]:
-        """
-        워크플로우 구조 검증
+    def validate_structure(self) -> List["ErrorInfo"]:
+        """Validate the workflow's structural invariants.
 
-        Returns:
-            검증 오류 메시지 목록 (빈 리스트면 유효)
+        Returns a list of `ErrorInfo` objects. An empty list means no
+        structural problems were found. Callers should append the result
+        to a `ValidationResult` via `result.add(...)` for each entry.
         """
-        errors = []
+        from programgarden_core.models.validation import (
+            ErrorCode,
+            ErrorInfo,
+            ErrorLocation,
+            build_error,
+        )
 
-        # 1. Duplicate node ID check
+        errors: List[ErrorInfo] = []
+
+        # 1. Duplicate node IDs
         node_ids = self.get_node_ids()
         if len(node_ids) != len(set(node_ids)):
-            seen = set()
-            dupes = [nid for nid in node_ids if nid in seen or seen.add(nid)]
-            errors.append(f"Duplicate node IDs found: {', '.join(dupes)}")
-
-        # 2. Edge node reference check
+            seen: set = set()
+            dupes: List[str] = []
+            for nid in node_ids:
+                if nid in seen and nid not in dupes:
+                    dupes.append(nid)
+                seen.add(nid)
+            for dup_id in dupes:
+                errors.append(
+                    build_error(
+                        ErrorCode.DUPLICATE_NODE_ID,
+                        f"Duplicate node id '{dup_id}'",
+                        location=ErrorLocation(node_id=dup_id),
+                        suggestion="Rename one of the duplicated nodes so each id is unique.",
+                    )
+                )
+
+        # 2. Edge node references
         node_id_set = set(node_ids)
-        for edge in self.edges:
+        for idx, edge in enumerate(self.edges):
             if edge.from_node_id not in node_id_set:
-                errors.append(f"Edge 'from' references non-existent node: {edge.from_node_id}")
+                errors.append(
+                    build_error(
+                        ErrorCode.INVALID_EDGE_REF,
+                        f"Edge 'from' references non-existent node '{edge.from_node_id}'",
+                        location=ErrorLocation(
+                            edge_index=idx,
+                            edge_from=edge.from_node_id,
+                            edge_to=edge.to_node_id,
+                        ),
+                        available_values=sorted(node_id_set),
+                    )
+                )
             if edge.to_node_id not in node_id_set:
-                errors.append(f"Edge 'to' references non-existent node: {edge.to_node_id}")
-
-        # 3. StartNode check
+                errors.append(
+                    build_error(
+                        ErrorCode.INVALID_EDGE_REF,
+                        f"Edge 'to' references non-existent node '{edge.to_node_id}'",
+                        location=ErrorLocation(
+                            edge_index=idx,
+                            edge_from=edge.from_node_id,
+                            edge_to=edge.to_node_id,
+                        ),
+                        available_values=sorted(node_id_set),
+                    )
+                )
+
+        # 3. StartNode invariants
         start_nodes = [n for n in self.nodes if n.get("type") == "StartNode"]
         if not start_nodes:
-            errors.append("StartNode is required (exactly 1 per workflow)")
+            errors.append(
+                build_error(
+                    ErrorCode.MISSING_START_NODE,
+                    "Workflow must contain exactly one StartNode",
+                    suggestion="Add a StartNode at the entry of the main flow.",
+                )
+            )
         elif len(start_nodes) > 1:
-            errors.append("Multiple StartNodes found (only 1 allowed per workflow)")
-
-        # 4. Cycle detection (DAG validation)
+            offending_ids = [n.get("id") for n in start_nodes if n.get("id")]
+            errors.append(
+                build_error(
+                    ErrorCode.MULTIPLE_START_NODES,
+                    f"Workflow has {len(start_nodes)} StartNodes; only one is allowed",
+                    location=ErrorLocation(
+                        node_id=offending_ids[0] if offending_ids else None,
+                        node_type="StartNode",
+                    ),
+                    suggestion="Keep one StartNode and remove the others (use ScheduleNode for cron triggers).",
+                    details={"start_node_ids": offending_ids},
+                )
+            )
+
+        # 4. Cycle detection
         cycle = self._detect_cycle()
         if cycle:
             cycle_path = " -> ".join(cycle)
-            errors.append(f"Circular reference detected: {cycle_path}")
+            errors.append(
+                build_error(
+                    ErrorCode.CYCLE_DETECTED,
+                    f"Cycle detected in the workflow DAG: {cycle_path}",
+                    location=ErrorLocation(node_id=cycle[0] if cycle else None),
+                    suggestion="Remove one of the edges in the cycle so execution order can be resolved.",
+                    details={"cycle_path": cycle},
+                )
+            )
 
         return errors
 

{programgarden_core-1.12.2 → programgarden_core-1.12.4}/programgarden_core/nodes/backtest_futures.py

@@ -23,6 +23,7 @@ from programgarden_core.nodes.base import (
     ProductScope,
     BrokerProvider,
     HISTORICAL_DATA_FIELDS,
+    HISTORICAL_VALUE_FIELDS,
 )
 
 
@@ -203,7 +204,7 @@ class OverseasFuturesHistoricalDataNode(BaseNode):
         InputPort(name="symbol", type="symbol", description="i18n:ports.symbol"),
     ]
     _outputs: List[OutputPort] = [
-        OutputPort(name="value", type="ohlcv_data", description="i18n:ports.ohlcv_value", fields=HISTORICAL_DATA_FIELDS),
+        OutputPort(name="value", type="ohlcv_data", description="i18n:ports.ohlcv_value", fields=HISTORICAL_VALUE_FIELDS),
     ]
 
     @classmethod

{programgarden_core-1.12.2 → programgarden_core-1.12.4}/programgarden_core/nodes/backtest_korea_stock.py

@@ -23,6 +23,7 @@ from programgarden_core.nodes.base import (
     ProductScope,
     BrokerProvider,
     HISTORICAL_DATA_FIELDS,
+    HISTORICAL_VALUE_FIELDS,
 )
 
 
@@ -202,7 +203,7 @@ class KoreaStockHistoricalDataNode(BaseNode):
         InputPort(name="symbol", type="symbol", description="i18n:ports.symbol"),
     ]
     _outputs: List[OutputPort] = [
-        OutputPort(name="value", type="ohlcv_data", description="i18n:ports.ohlcv_value", fields=HISTORICAL_DATA_FIELDS),
+        OutputPort(name="value", type="ohlcv_data", description="i18n:ports.ohlcv_value", fields=HISTORICAL_VALUE_FIELDS),
     ]
 
     @classmethod

{programgarden_core-1.12.2 → programgarden_core-1.12.4}/programgarden_core/nodes/backtest_stock.py

@@ -23,6 +23,7 @@ from programgarden_core.nodes.base import (
     ProductScope,
     BrokerProvider,
     HISTORICAL_DATA_FIELDS,
+    HISTORICAL_VALUE_FIELDS,
 )
 
 
@@ -209,7 +210,7 @@ class OverseasStockHistoricalDataNode(BaseNode):
             name="value",
             type="ohlcv_data",
             description="i18n:ports.ohlcv_value",
-            fields=HISTORICAL_DATA_FIELDS,
+            fields=HISTORICAL_VALUE_FIELDS,
             example=[
                 {
                     "symbol": "AAPL",
@@ -221,6 +222,26 @@ class OverseasStockHistoricalDataNode(BaseNode):
                 },
             ],
         ),
+        OutputPort(
+            name="values",
+            type="array",
+            description="Array form of all fetched series — [{symbol, exchange, time_series: [...]}, ...]",
+        ),
+        OutputPort(
+            name="symbols",
+            type="array",
+            description="Flat list of fetched symbol strings",
+        ),
+        OutputPort(
+            name="period",
+            type="string",
+            description="Date range string formatted as 'YYYYMMDD~YYYYMMDD'",
+        ),
+        OutputPort(
+            name="interval",
+            type="string",
+            description="Candle interval (D / W / M)",
+        ),
     ]
 
     @classmethod

{programgarden_core-1.12.2 → programgarden_core-1.12.4}/programgarden_core/nodes/base.py

@@ -259,6 +259,18 @@ HISTORICAL_DATA_FIELDS: List[Dict[str, str]] = [
     {"name": "volume", "type": "number", "description": "거래량"},
 ]
 
+# Outer shape of HistoricalDataNode's `value` port. The runtime payload
+# is {symbol, exchange, time_series: [HISTORICAL_DATA_FIELDS, ...]}.
+# Previously the schema attached HISTORICAL_DATA_FIELDS directly to the
+# `value` port, which (correctly) declared the bar shape but (incorrectly)
+# made expressions like `{{ nodes.historical.value.time_series }}`
+# look like field typos against the schema.
+HISTORICAL_VALUE_FIELDS: List[Dict[str, str]] = [
+    {"name": "symbol", "type": "string", "description": "종목코드"},
+    {"name": "exchange", "type": "string", "description": "거래소 코드"},
+    {"name": "time_series", "type": "array", "description": "OHLCV 바 배열"},
+]
+
 ORDER_LIST_FIELDS: List[Dict[str, str]] = [
     {"name": "order_id", "type": "string", "description": "주문번호"},
     {"name": "exchange", "type": "string", "description": "거래소 코드"},

{programgarden_core-1.12.2 → programgarden_core-1.12.4}/programgarden_core/nodes/condition.py

@@ -86,18 +86,41 @@ class ConditionNode(PluginNode):
     _outputs: List[OutputPort] = [
         OutputPort(
             name="result",
-            type="condition_result",
-            description="i18n:ports.condition_result",
-            fields=CONDITION_RESULT_FIELDS,
-            example={
-                "is_condition_met": True,
-                "passed_symbols": [
-                    {"exchange": "NASDAQ", "symbol": "AAPL"},
-                ],
-                "details": [
-                    {"symbol": "AAPL", "exchange": "NASDAQ", "passed": True, "value": 28.5, "threshold": 30, "direction": "below"},
-                ],
-            },
+            type="boolean",
+            description="True if any symbol passed the condition (len(passed_symbols) > 0)",
+        ),
+        OutputPort(
+            name="is_condition_met",
+            type="boolean",
+            description="Alias of result — convenience for IfNode/LogicNode bindings",
+        ),
+        OutputPort(
+            name="symbols",
+            type="symbol_list",
+            description="Input symbols normalized to [{exchange, symbol}, ...]",
+            fields=SYMBOL_LIST_FIELDS,
+        ),
+        OutputPort(
+            name="passed_symbols",
+            type="symbol_list",
+            description="Symbols that satisfied the condition — [{exchange, symbol}, ...]",
+            fields=SYMBOL_LIST_FIELDS,
+        ),
+        OutputPort(
+            name="failed_symbols",
+            type="symbol_list",
+            description="Symbols that did not satisfy the condition — [{exchange, symbol}, ...]",
+            fields=SYMBOL_LIST_FIELDS,
+        ),
+        OutputPort(
+            name="symbol_results",
+            type="array",
+            description="Per-symbol breakdown — [{symbol, exchange, passed, value, ...plugin-specific fields}, ...]",
+        ),
+        OutputPort(
+            name="values",
+            type="array",
+            description="Per-symbol time series — [{symbol, exchange, time_series: [...]}, ...] (empty for position plugins)",
         ),
     ]
 
@@ -378,22 +401,19 @@ class LogicNode(BaseNode):
     _outputs: List[OutputPort] = [
         OutputPort(
             name="result",
-            type="condition_result",
-            description="i18n:ports.result",
-            fields=CONDITION_RESULT_FIELDS,
-            example={
-                "is_condition_met": True,
-                "passed_symbols": [{"exchange": "NASDAQ", "symbol": "AAPL"}],
-            },
+            type="boolean",
+            description="Combined boolean result (true when the configured operator is satisfied)",
         ),
         OutputPort(
             name="passed_symbols",
             type="symbol_list",
-            description="i18n:ports.passed_symbols",
+            description="Symbols satisfying the combined condition (intersection/union depending on operator)",
             fields=SYMBOL_LIST_FIELDS,
-            example=[
-                {"exchange": "NASDAQ", "symbol": "AAPL"},
-            ],
+        ),
+        OutputPort(
+            name="details",
+            type="array",
+            description="Per-condition breakdown — [{is_condition_met, passed_symbols, weight?, ...}, ...]",
         ),
     ]
 

{programgarden_core-1.12.2 → programgarden_core-1.12.4}/programgarden_core/nodes/data.py

@@ -1196,6 +1196,11 @@ class FieldMappingNode(BaseNode):
             type="any",
             description="i18n:ports.mapped_data",
         ),
+        OutputPort(
+            name="data",
+            type="any",
+            description="Alias of mapped_data — convenient when chaining into nodes that expect 'data'",
+        ),
         OutputPort(
             name="original_fields",
             type="array",
@@ -1335,6 +1340,7 @@ class FieldMappingNode(BaseNode):
 
         return {
             "mapped_data": mapped_data,
+            "data": mapped_data,  # alias declared in _outputs — downstream nodes that expect 'data'
             "original_fields": sorted(list(original_fields)),
             "mapped_fields": sorted(list(mapped_fields)),
         }

{programgarden_core-1.12.2 → programgarden_core-1.12.4}/programgarden_core/nodes/data_korea_stock.py

@@ -191,6 +191,7 @@ class KoreaStockMarketDataNode(BaseNode):
     ]
     _outputs: List[OutputPort] = [
         OutputPort(name="value", type="market_data", description="i18n:ports.market_data_value", fields=KOREA_STOCK_PRICE_DATA_FIELDS),
+        OutputPort(name="values", type="array", description="Array of per-symbol market quotes"),
     ]
 
     @classmethod

{programgarden_core-1.12.2 → programgarden_core-1.12.4}/programgarden_core/nodes/data_stock.py

@@ -206,6 +206,11 @@ class OverseasStockMarketDataNode(BaseNode):
                 "eps": 6.57,
             },
         ),
+        OutputPort(
+            name="values",
+            type="array",
+            description="Array of per-symbol market quotes — [{symbol, exchange, current_price, ...}, ...]",
+        ),
     ]
 
     @classmethod

{programgarden_core-1.12.2 → programgarden_core-1.12.4}/programgarden_core/nodes/fundamental_korea_stock.py

@@ -188,6 +188,7 @@ class KoreaStockFundamentalNode(BaseNode):
     ]
     _outputs: List[OutputPort] = [
         OutputPort(name="value", type="fundamental_data", description="i18n:ports.fundamental_data_value", fields=KOREA_STOCK_FUNDAMENTAL_FIELDS),
+        OutputPort(name="values", type="array", description="Array of per-symbol fundamental records"),
     ]
 
     @classmethod

{programgarden_core-1.12.2 → programgarden_core-1.12.4}/programgarden_core/nodes/fundamental_stock.py

@@ -187,6 +187,7 @@ class OverseasStockFundamentalNode(BaseNode):
     ]
     _outputs: List[OutputPort] = [
         OutputPort(name="value", type="fundamental_data", description="i18n:ports.fundamental_data_value", fields=FUNDAMENTAL_DATA_FIELDS),
+        OutputPort(name="values", type="array", description="Array of per-symbol fundamental records"),
     ]
 
     @classmethod

{programgarden_core-1.12.2 → programgarden_core-1.12.4}/programgarden_core/nodes/infra.py

@@ -414,6 +414,11 @@ class SplitNode(BaseNode):
             description="i18n:ports.split_total",
             example=3,
         ),
+        OutputPort(
+            name="items",
+            type="array",
+            description="Full input array (same as the upstream array) — convenient for downstream binding",
+        ),
     ]
 
     _usage: ClassVar[Dict[str, Any]] = {

{programgarden_core-1.12.2 → programgarden_core-1.12.4}/programgarden_core/nodes/portfolio.py

@@ -157,6 +157,12 @@ class PortfolioNode(BaseNode):
             description="i18n:ports.allocated_capital",
             fields=ALLOCATED_CAPITAL_FIELDS,
         ),
+        # 위험 감시 단축
+        OutputPort(
+            name="drawdown_percent",
+            type="number",
+            description="Current drawdown as percentage (shortcut to combined_metrics.max_drawdown for IfNode kill switches)",
+        ),
     ]
 
     _usage: ClassVar[Dict[str, Any]] = {

{programgarden_core-1.12.2 → programgarden_core-1.12.4}/programgarden_core/nodes/symbol.py

@@ -400,6 +400,14 @@ class ScreenerNode(BaseNode):
         default=None,
         description="최소 평균 거래량 (주). 예: 1000000 = 100만주",
     )
+    price_min: Optional[float] = Field(
+        default=None,
+        description="최소 주가 ($). 예: 1.0 = $1 이상. 동전주 발굴 등 가격대 필터링에 사용",
+    )
+    price_max: Optional[float] = Field(
+        default=None,
+        description="최대 주가 ($). 예: 5.0 = $5 이하. 동전주 발굴 등 가격대 필터링에 사용",
+    )
     sector: Optional[str] = Field(
         default=None,
         description="섹터 필터 (Technology, Healthcare, Finance 등)",
@@ -409,10 +417,15 @@ class ScreenerNode(BaseNode):
         description="거래소 필터 (NASDAQ, NYSE, AMEX)",
     )
     max_results: int = Field(
-        default=100, 
+        default=100,
         description="최대 결과 수"
     )
 
+    data_source: Literal["auto", "ls", "yfinance"] = Field(
+        default="auto",
+        description="자료 가져올 곳. auto=브로커 연결 시 LS증권, 아니면 Yahoo Finance. ls=LS증권 강제. yfinance=Yahoo Finance 강제.",
+    )
+
     _inputs: List[InputPort] = [
         InputPort(
             name="symbols",
@@ -582,6 +595,29 @@ class ScreenerNode(BaseNode):
                 placeholder="예: 1000000 (100만주)",
                 expected_type="int",
             ),
+            # === PARAMETERS: 가격 필터 ===
+            "price_min": FieldSchema(
+                name="price_min",
+                type=FieldType.NUMBER,
+                description="최소 주가 (달러). 동전주 발굴이나 저가주 필터링에 사용하세요. 예: 1.0 = $1 이상.",
+                required=False,
+                category=FieldCategory.PARAMETERS,
+                expression_mode=ExpressionMode.FIXED_ONLY,
+                example=1.0,
+                placeholder="예: 1.0 ($1 이상)",
+                expected_type="float",
+            ),
+            "price_max": FieldSchema(
+                name="price_max",
+                type=FieldType.NUMBER,
+                description="최대 주가 (달러). 고가주 제외나 동전주 상한선 설정에 사용하세요. 예: 5.0 = $5 이하.",
+                required=False,
+                category=FieldCategory.PARAMETERS,
+                expression_mode=ExpressionMode.FIXED_ONLY,
+                example=5.0,
+                placeholder="예: 5.0 ($5 이하)",
+                expected_type="float",
+            ),
             # === PARAMETERS: 섹터/거래소 필터 ===
             "sector": FieldSchema(
                 name="sector",
@@ -625,6 +661,23 @@ class ScreenerNode(BaseNode):
                 example="NASDAQ",
                 expected_type="str",
             ),
+            # === PARAMETERS: 자료 가져올 곳 ===
+            "data_source": FieldSchema(
+                name="data_source",
+                type=FieldType.ENUM,
+                description="가격/시가총액/거래량 정보를 어디에서 받아올지 선택하세요. '자동'을 권장합니다.",
+                default="auto",
+                enum_values=["auto", "ls", "yfinance"],
+                enum_labels={
+                    "auto": "자동 (브로커 연결 시 LS증권 사용, 없으면 Yahoo Finance)",
+                    "ls": "LS증권 (빠름, 브로커 연결 필요)",
+                    "yfinance": "Yahoo Finance (외부 API)",
+                },
+                category=FieldCategory.PARAMETERS,
+                expression_mode=ExpressionMode.FIXED_ONLY,
+                example="auto",
+                expected_type="str",
+            ),
             # === SETTINGS: 결과 제한 ===
             "max_results": FieldSchema(
                 name="max_results",

{programgarden_core-1.12.2 → programgarden_core-1.12.4}/pyproject.toml

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