programgarden-core 1.31.0__tar.gz → 2.0.1__tar.gz

{programgarden_core-1.31.0 → programgarden_core-2.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: programgarden-core
-Version: 1.31.0
+Version: 2.0.1
 Summary: ProgramGarden Core - 노드 기반 DSL 핵심 타입 정의
 License-Expression: AGPL-3.0-or-later
 Author: 프로그램동산
@@ -10,7 +10,7 @@ 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: pydantic (>=2.0.0,<3.0.0)
+Requires-Dist: pydantic (>=2.0.1,<3.0.0)
 Requires-Dist: tzdata (>=2025.2,<2026.0)
 Description-Content-Type: text/markdown
 
@@ -59,7 +59,7 @@ poetry add programgarden-core
 | analysis | 2 | BacktestEngineNode, BenchmarkCompareNode |
 | ai | 2 | LLMModelNode, AIAgentNode |
 
-> Community adds five nodes: TelegramNode, FearGreedIndexNode, FundamentalDataNode, FileReaderNode and PerformanceReportNode, for 78 total.
+> Community adds four nodes: TelegramNode, FearGreedIndexNode, FileReaderNode and PerformanceReportNode, for 77 total.
 
 ## 사용 예시
 

{programgarden_core-1.31.0 → programgarden_core-2.0.1}/README.md

@@ -43,7 +43,7 @@ poetry add programgarden-core
 | analysis | 2 | BacktestEngineNode, BenchmarkCompareNode |
 | ai | 2 | LLMModelNode, AIAgentNode |
 
-> Community adds five nodes: TelegramNode, FearGreedIndexNode, FundamentalDataNode, FileReaderNode and PerformanceReportNode, for 78 total.
+> Community adds four nodes: TelegramNode, FearGreedIndexNode, FileReaderNode and PerformanceReportNode, for 77 total.
 
 ## 사용 예시
 

{programgarden_core-1.31.0 → programgarden_core-2.0.1}/programgarden_core/expression/evaluator.py

@@ -149,6 +149,21 @@ class DateNamespace:
         'iso': '%Y-%m-%d',
     }
 
+    def __init__(self, *, as_of: Optional[str] = None):
+        """Optionally pin replay helpers to an explicit timezone-aware instant.
+
+        Live callers omit as_of and retain their existing local-clock behavior.
+        The execution host, never a model-supplied node setting, owns this clock.
+        """
+        self._as_of = None
+        if as_of is not None:
+            self._as_of = datetime.fromisoformat(as_of.replace("Z", "+00:00"))
+            if self._as_of.tzinfo is None or self._as_of.utcoffset() is None:
+                raise ValueError("Replay as_of must include its timezone")
+
+    def _today(self) -> date:
+        return self._as_of.date() if self._as_of is not None else date.today()
+
     def _format_date(self, d: date, fmt: Optional[str] = None) -> str:
         """날짜를 지정된 포맷으로 변환"""
         if fmt is None:
@@ -159,40 +174,40 @@ class DateNamespace:
 
     def today(self, format: Optional[str] = None) -> str:
         """오늘 날짜"""
-        return self._format_date(date.today(), format)
+        return self._format_date(self._today(), format)
 
     def now(self) -> str:
         """현재 시간 (ISO 형식)"""
-        return datetime.now().isoformat()[:19]
+        return self._as_of.isoformat(timespec="seconds") if self._as_of is not None else datetime.now().isoformat()[:19]
 
     def ago(self, days: int, format: Optional[str] = None) -> str:
         """n일 전"""
-        d = date.today() - timedelta(days=int(days))
+        d = self._today() - timedelta(days=int(days))
         return self._format_date(d, format)
 
     def later(self, days: int, format: Optional[str] = None) -> str:
         """n일 후"""
-        d = date.today() + timedelta(days=int(days))
+        d = self._today() + timedelta(days=int(days))
         return self._format_date(d, format)
 
     def months_ago(self, months: int, format: Optional[str] = None) -> str:
         """n개월 전 (30일 기준)"""
-        d = date.today() - timedelta(days=int(months) * 30)
+        d = self._today() - timedelta(days=int(months) * 30)
         return self._format_date(d, format)
 
     def year_start(self, format: Optional[str] = None) -> str:
         """연초 (1월 1일)"""
-        d = date(date.today().year, 1, 1)
+        d = date(self._today().year, 1, 1)
         return self._format_date(d, format)
 
     def year_end(self, format: Optional[str] = None) -> str:
         """연말 (12월 31일)"""
-        d = date(date.today().year, 12, 31)
+        d = date(self._today().year, 12, 31)
         return self._format_date(d, format)
 
     def month_start(self, format: Optional[str] = None) -> str:
         """월초"""
-        d = date.today().replace(day=1)
+        d = self._today().replace(day=1)
         return self._format_date(d, format)
 
 

{programgarden_core-1.31.0 → programgarden_core-2.0.1}/programgarden_core/i18n/locales/en.json

@@ -64,8 +64,6 @@
   "nodes.EventHandlerNode.name": "Event Handler",
   "nodes.FearGreedIndexNode.description": "Fetches the CNN Fear & Greed Index, a market sentiment indicator ranging from 0 (Extreme Fear) to 100 (Extreme Greed). No broker connection or API key required. Outputs the current index value (0-100), label (Extreme Fear / Fear / Neutral / Greed / Extreme Greed), and previous day's close value. Built-in resilience with retry on API failures. Typical connection: FearGreedIndexNode → ConditionNode (for sentiment-based trading signals) or → SummaryDisplayNode.",
   "nodes.FearGreedIndexNode.name": "Fear & Greed Index",
-  "nodes.FundamentalDataNode.description": "Fetches company financial data via Financial Modeling Prep (FMP) API. Supports four data types: company profile, income statement, balance sheet, and key metrics. Configure period (annual/quarter) and limit (number of periods to fetch). Requires FMP API credentials. Outputs financial data array and query summary. Typical connection: WatchlistNode → FundamentalDataNode → ConditionNode (for fundamental screening) or → TableDisplayNode.",
-  "nodes.FundamentalDataNode.name": "Fundamental Data (FMP)",
   "nodes.PerformanceReportNode.name": "Performance Report (quantstats)",
   "nodes.PerformanceReportNode.description": "Computes risk/return metrics (Sharpe, Sortino, max drawdown, CAGR, annualized volatility, Calmar) from an equity curve, price series, or return series using quantstats. Optionally computes beta and alpha against a benchmark series. Emits a drawdown time series and a formatted text report, and runs headless via the matplotlib Agg backend. Requires the optional 'perf' extra (pip install 'programgarden-community[perf]'); a missing or partially-installed extra raises a structured MissingDependencyError. Typical connection: BacktestEngineNode → PerformanceReportNode → TableDisplayNode.",
   "nodes.FieldMappingNode.description": "Renames field names in data objects to a standard format. Use to normalize external API responses so downstream nodes can access data with consistent field names (e.g., rename 'adj_close' to 'close', 'vol' to 'volume'). Configure mappings as from/to pairs. Outputs mapped_data with renamed fields. Set preserve_unmapped=true to keep original fields alongside renamed ones. Note: this node only renames fields — it does not generate or transform data values. Typical connection: HTTPRequestNode → FieldMappingNode → ConditionNode.",
@@ -318,13 +316,6 @@
   "fields.FileReaderNode.max_file_size_mb": "Maximum file size per file (MB). Range 1-50, default 10MB.",
   "fields.FearGreedIndexNode.resilience": "Retry and fallback settings for API call failures",
   "fields.FearGreedIndexNode.timeout_seconds": "API request timeout (seconds). Default 30s, adjust based on your network conditions.",
-  "fields.FundamentalDataNode.credential_id": "FMP API credentials. Register your API key from financialmodelingprep.com.",
-  "fields.FundamentalDataNode.symbols": "Symbols to query. [{symbol, exchange}] format.",
-  "fields.FundamentalDataNode.data_type": "Data type: profile, income_statement, balance_sheet, key_metrics",
-  "fields.FundamentalDataNode.period": "Period: annual or quarter. Used for financial statements and key metrics.",
-  "fields.FundamentalDataNode.limit": "Number of periods to fetch (most recent N). Default 1.",
-  "fields.FundamentalDataNode.timeout_seconds": "API request timeout (seconds). Default 30s.",
-  "fields.FundamentalDataNode.resilience": "Retry and fallback settings for API call failures",
   "fields.PerformanceReportNode.data": "Input series: an array of numbers or of {date, <value_field>} objects (equity curve, price levels, or periodic returns).",
   "fields.PerformanceReportNode.data_kind": "Kind of the input series: 'equity', 'prices', or 'returns'. Level series ('equity'/'prices') are converted to returns internally.",
   "fields.PerformanceReportNode.value_field": "Key holding the numeric value when rows are objects (default 'close'; falls back to value/equity/return).",
@@ -655,13 +646,6 @@
   "fieldNames.FileReaderNode.max_file_size_mb": "Max Size (MB)",
   "fieldNames.FearGreedIndexNode.resilience": "Resilience",
   "fieldNames.FearGreedIndexNode.timeout_seconds": "Timeout (sec)",
-  "fieldNames.FundamentalDataNode.credential_id": "FMP Credential",
-  "fieldNames.FundamentalDataNode.symbols": "Symbols",
-  "fieldNames.FundamentalDataNode.data_type": "Data Type",
-  "fieldNames.FundamentalDataNode.period": "Period",
-  "fieldNames.FundamentalDataNode.limit": "Limit",
-  "fieldNames.FundamentalDataNode.timeout_seconds": "Timeout (sec)",
-  "fieldNames.FundamentalDataNode.resilience": "Resilience",
   "fieldNames.PerformanceReportNode.data": "Data Series",
   "fieldNames.PerformanceReportNode.data_kind": "Data Kind",
   "fieldNames.PerformanceReportNode.value_field": "Value Field",
@@ -886,8 +870,6 @@
   "outputs.FearGreedIndexNode.label": "Index label (Extreme Fear / Fear / Neutral / Greed / Extreme Greed)",
   "outputs.FearGreedIndexNode.previous_close": "Previous day's Fear & Greed Index value",
   "outputs.FearGreedIndexNode.value": "Fear & Greed Index (0~100)",
-  "outputs.FundamentalDataNode.data": "Financial data array [{symbol, exchange, ...}]",
-  "outputs.FundamentalDataNode.summary": "Query summary {data_type, symbol_count, record_count}",
   "outputs.PerformanceReportNode.metrics": "Metrics object {sharpe, sortino, max_drawdown, cagr, volatility, calmar[, beta, alpha]} (null on insufficient data).",
   "outputs.PerformanceReportNode.report": "Formatted multi-line performance report text.",
   "outputs.PerformanceReportNode.drawdown_series": "Drawdown time series as an array of {date, drawdown}.",

{programgarden_core-1.31.0 → programgarden_core-2.0.1}/programgarden_core/i18n/locales/ko.json

@@ -68,8 +68,6 @@
   "nodes.FileReaderNode.name": "파일 리더",
   "nodes.FearGreedIndexNode.description": "CNN 공포/탐욕 지수를 조회합니다. 0(극단적 공포)부터 100(극단적 탐욕)까지의 시장 심리 지표입니다. 브로커 연결이나 API 키가 필요 없습니다. 출력: 현재 지수값(0-100), 라벨(Extreme Fear / Fear / Neutral / Greed / Extreme Greed), 전일 종가. API 오류 시 자동 재시도 기능 내장. 일반적인 연결: FearGreedIndexNode → ConditionNode (심리 기반 매매 시그널) 또는 → SummaryDisplayNode.",
   "nodes.FearGreedIndexNode.name": "공포/탐욕 지수",
-  "nodes.FundamentalDataNode.description": "Financial Modeling Prep (FMP) API로 기업 재무 데이터를 조회합니다. 4가지 데이터 유형: 기업 프로필, 손익계산서, 대차대조표, 핵심 지표. 기간(연간/분기)과 조회 수(최근 N기)를 설정합니다. FMP API 인증 정보 필요. 출력: 재무 데이터 배열, 조회 요약. 일반적인 연결: WatchlistNode → FundamentalDataNode → ConditionNode (펀더멘털 스크리닝) 또는 → TableDisplayNode.",
-  "nodes.FundamentalDataNode.name": "재무 데이터 (FMP)",
   "nodes.PerformanceReportNode.name": "성과 리포트 (quantstats)",
   "nodes.PerformanceReportNode.description": "자산곡선(equity)·가격·수익률 시계열로부터 quantstats 로 리스크·수익 지표(Sharpe, Sortino, 최대낙폭, CAGR, 연율 변동성, Calmar)를 산출합니다. 벤치마크 시계열을 지정하면 beta/alpha 를 추가로 계산합니다. 낙폭 시계열과 서식 리포트 텍스트를 출력하며, matplotlib Agg 백엔드로 헤드리스 동작합니다. 선택 'perf' extra 필요(pip install 'programgarden-community[perf]') — 미설치/부분설치 시 구조화된 MissingDependencyError 를 발생시킵니다. 대표 연결: BacktestEngineNode → PerformanceReportNode → TableDisplayNode.",
   "nodes.HTTPRequestNode.description": "GET, POST, PUT, PATCH, DELETE를 지원하는 외부 REST API 호출 노드입니다. URL({{ }} 표현식 지원), 헤더, 쿼리 파라미터, JSON 요청 본문을 설정합니다. 인증 방식: Bearer 토큰, 헤더 키, 기본 인증, 쿼리 파라미터. 서버 에러(5xx), 속도 제한(429), 네트워크 장애 시 자동 재시도 기능 내장. 출력: 응답 데이터, HTTP 상태 코드, 응답 헤더, 응답 시간(ms). 실시간 데이터 소스 연결 시 ThrottleNode 필수. 일반적인 연결: ThrottleNode → HTTPRequestNode → FieldMappingNode. AI Agent 도구로 사용 가능.",
@@ -318,13 +316,6 @@
   "fields.FileReaderNode.max_file_size_mb": "파일당 최대 크기 (MB). 1~50, 기본 10MB.",
   "fields.FearGreedIndexNode.resilience": "API 호출 실패 시 재시도 및 폴백 설정",
   "fields.FearGreedIndexNode.timeout_seconds": "API 요청 타임아웃 (초). 기본 30초, 네트워크 환경에 따라 조정하세요.",
-  "fields.FundamentalDataNode.credential_id": "FMP API 인증 정보. financialmodelingprep.com에서 발급받은 API 키를 등록하세요.",
-  "fields.FundamentalDataNode.symbols": "조회할 종목 목록. [{symbol, exchange}] 형식.",
-  "fields.FundamentalDataNode.data_type": "데이터 유형: profile(기업정보), income_statement(손익계산서), balance_sheet(대차대조표), key_metrics(핵심지표)",
-  "fields.FundamentalDataNode.period": "기간: annual(연간), quarter(분기). 재무제표/핵심지표 조회 시 사용.",
-  "fields.FundamentalDataNode.limit": "가져올 기간 수 (최근 N개). 기본 1.",
-  "fields.FundamentalDataNode.timeout_seconds": "API 요청 타임아웃 (초). 기본 30초.",
-  "fields.FundamentalDataNode.resilience": "API 호출 실패 시 재시도 및 폴백 설정",
   "fields.PerformanceReportNode.data": "입력 시계열: 숫자 배열 또는 {date, <value_field>} 객체 배열(자산곡선/가격/수익률).",
   "fields.PerformanceReportNode.data_kind": "입력 종류: 'equity'/'prices'/'returns'. 레벨 시계열('equity'/'prices')은 내부에서 수익률로 변환됩니다.",
   "fields.PerformanceReportNode.value_field": "행이 객체일 때 숫자 값을 담은 키(기본 'close'; value/equity/return 폴백).",
@@ -655,13 +646,6 @@
   "fieldNames.FileReaderNode.max_file_size_mb": "최대크기(MB)",
   "fieldNames.FearGreedIndexNode.resilience": "재시도설정",
   "fieldNames.FearGreedIndexNode.timeout_seconds": "타임아웃(초)",
-  "fieldNames.FundamentalDataNode.credential_id": "FMP 인증",
-  "fieldNames.FundamentalDataNode.symbols": "종목",
-  "fieldNames.FundamentalDataNode.data_type": "데이터유형",
-  "fieldNames.FundamentalDataNode.period": "기간",
-  "fieldNames.FundamentalDataNode.limit": "조회수",
-  "fieldNames.FundamentalDataNode.timeout_seconds": "타임아웃(초)",
-  "fieldNames.FundamentalDataNode.resilience": "재시도설정",
   "fieldNames.PerformanceReportNode.data": "데이터 시계열",
   "fieldNames.PerformanceReportNode.data_kind": "데이터 종류",
   "fieldNames.PerformanceReportNode.value_field": "값 필드",
@@ -886,8 +870,6 @@
   "outputs.FearGreedIndexNode.label": "지수 라벨 (Extreme Fear / Fear / Neutral / Greed / Extreme Greed)",
   "outputs.FearGreedIndexNode.previous_close": "전일 공포/탐욕 지수",
   "outputs.FearGreedIndexNode.value": "공포/탐욕 지수 (0~100)",
-  "outputs.FundamentalDataNode.data": "재무 데이터 배열 [{symbol, exchange, ...}]",
-  "outputs.FundamentalDataNode.summary": "조회 요약 {data_type, symbol_count, record_count}",
   "outputs.PerformanceReportNode.metrics": "지표 객체 {sharpe, sortino, max_drawdown, cagr, volatility, calmar[, beta, alpha]} (데이터 부족 시 null).",
   "outputs.PerformanceReportNode.report": "서식 성과 리포트 텍스트.",
   "outputs.PerformanceReportNode.drawdown_series": "낙폭 시계열 [{date, drawdown}] 배열.",

{programgarden_core-1.31.0 → programgarden_core-2.0.1}/programgarden_core/models/credential.py

@@ -861,3 +861,8 @@ class DBCredential(BaseModel):
         elif self.db_type == DBType.MYSQL:
             return f"mysql://{self.username}:{self.password}@{self.host}:{self.port}/{self.database}"
         raise ValueError(f"Unsupported db_type: {self.db_type}")
+
+# Keep the published native "telegram" type readable while the platform uses telegram_bot.
+BUILTIN_CREDENTIAL_SCHEMAS["telegram_bot"] = BUILTIN_CREDENTIAL_SCHEMAS["telegram"].model_copy(
+    update={"type_id": "telegram_bot"}
+)

{programgarden_core-1.31.0 → programgarden_core-2.0.1}/programgarden_core/nodes/fundamental_stock.py

@@ -64,7 +64,7 @@ class OverseasStockFundamentalNode(BaseNode):
 
     _usage: ClassVar[Dict[str, Any]] = {
         "when_to_use": [
-            "Retrieve fundamental valuation data (PER, EPS, PBR, market cap, 52w high/low, sector) for a US-listed stock",
+            "Retrieve LS security-detail data (PER, EPS, market cap, 52w high/low, industry) for a US-listed stock using the existing broker connection",
             "Screen or rank stocks by fundamental criteria — pair with ConditionNode or FieldMappingNode for filtering",
             "Give an AI Agent context about a stock's valuation alongside price data for investment thesis generation",
         ],
@@ -72,6 +72,7 @@ class OverseasStockFundamentalNode(BaseNode):
             "For Korean domestic stock fundamentals — use KoreaStockFundamentalNode",
             "When you only need price/volume data — use OverseasStockMarketDataNode",
             "For real-time earnings or news events — fundamental data is updated daily, not tick-by-tick",
+            "For financial-statement history, free cash flow, ROE or PBR — these are not returned by this node; use a separately verified data source",
         ],
         "typical_scenarios": [
             "SplitNode.item → OverseasStockFundamentalNode → ConditionNode (filter by PER < 20)",
@@ -80,7 +81,8 @@ class OverseasStockFundamentalNode(BaseNode):
         ],
     }
     _features: ClassVar[List[str]] = [
-        "Returns per, pbr, eps, market_cap, shares_outstanding, 52w_high, 52w_low, sector, industry fields",
+        "Returns per, eps, market_cap, shares_outstanding, high_52w, low_52w and industry fields",
+        "Uses the LS overseas-stock broker credential; no separate financial-data subscription key is required",
         "Item-based execution: pair with SplitNode to fetch fundamentals for each symbol in a universe",
         "is_tool_enabled=True — AI Agent can call this node to analyze stock valuation autonomously",
         "Broker connection is auto-injected via DAG traversal from OverseasStockBrokerNode",
@@ -130,7 +132,7 @@ class OverseasStockFundamentalNode(BaseNode):
                     }
                 ],
             },
-            "expected_output": "value port: {symbol, exchange, per, pbr, eps, market_cap, shares_outstanding, 52w_high, 52w_low, sector, industry}.",
+            "expected_output": "value port: {symbol, exchange, per, eps, market_cap, shares_outstanding, high_52w, low_52w, industry}.",
         },
         {
             "title": "Fundamental screening — filter low-PER stocks",
@@ -172,7 +174,7 @@ class OverseasStockFundamentalNode(BaseNode):
             "Supported exchanges: NYSE, NASDAQ, AMEX. Broker connection is auto-injected."
         ),
         "output_consumption": (
-            "The `value` port emits: {symbol, exchange, per, pbr, eps, market_cap, shares_outstanding, 52w_high, 52w_low, sector, industry}. "
+            "The `value` port emits: {symbol, exchange, per, eps, market_cap, shares_outstanding, high_52w, low_52w, industry}. "
             "Access individual fields via `{{ nodes.fundamental.value.per }}`."
         ),
         "common_combinations": [
@@ -182,7 +184,8 @@ class OverseasStockFundamentalNode(BaseNode):
         ],
         "pitfalls": [
             "Fundamental data is updated daily — do not use it as a real-time signal",
-            "PER may be null for pre-earnings or non-profitable companies — add null-check in ConditionNode logic",
+            "Missing broker fields can be empty or zero. For a positive-PER screen require a finite numeric per > 0 before comparing the upper bound; missing/zero/negative data must not create a buy signal",
+            "LS does not document the PER computation basis or the market-cap currency unit here. Do not claim TTM equivalence or compare cross-provider values without confirming the contract",
             "The symbol field expects a single dict; use SplitNode for multi-symbol fundamental queries",
         ],
     }

{programgarden_core-1.31.0 → programgarden_core-2.0.1}/pyproject.toml

@@ -5,7 +5,7 @@ authors = [
 homepage = "https://programgarden.com"
 requires-python = ">=3.12"
 name = "programgarden-core"
-version = "1.31.0"
+version = "2.0.1"
 license = "AGPL-3.0-or-later"
 description = "ProgramGarden Core - 노드 기반 DSL 핵심 타입 정의"
 readme = "README.md"
@@ -16,7 +16,7 @@ packages = [
 ]
 
 [tool.poetry.dependencies]
-pydantic = ">=2.0.0,<3.0.0"
+pydantic = ">=2.0.1,<3.0.0"
 tzdata = "^2025.2"
 
 [tool.poetry.group.dev.dependencies]
@@ -26,5 +26,5 @@ mypy = "^1.0.0"
 ruff = "^0.1.0"
 
 [build-system]
-requires = ["poetry-core>=2.0.0,<3.0.0"]
+requires = ["poetry-core>=2.0.1,<3.0.0"]
 build-backend = "poetry.core.masonry.api"