quantwise 1.2.0 → 1.2.2

package/.claude/skills/economic-calendar-fetcher/scripts/get_economic_calendar.py

@@ -0,0 +1,267 @@
+#!/usr/bin/env python3
+"""
+Economic Calendar Fetcher using FMP API
+Retrieves economic events and data releases for specified date range
+"""
+
+import os
+import sys
+import json
+import argparse
+from datetime import datetime, timedelta
+from typing import Dict, List, Optional
+import urllib.request
+import urllib.error
+import urllib.parse
+
+
+def get_api_key() -> Optional[str]:
+    """
+    Get FMP API key from environment variable.
+
+    Returns:
+        API key string or None if not found
+    """
+    api_key = os.environ.get('FMP_API_KEY')
+    if not api_key:
+        print("Warning: FMP_API_KEY environment variable not set", file=sys.stderr)
+    return api_key
+
+
+def fetch_economic_calendar(
+    from_date: str,
+    to_date: str,
+    api_key: str
+) -> List[Dict]:
+    """
+    Fetch economic calendar data from FMP API.
+
+    Args:
+        from_date: Start date in YYYY-MM-DD format
+        to_date: End date in YYYY-MM-DD format
+        api_key: FMP API key
+
+    Returns:
+        List of economic event dictionaries
+
+    Raises:
+        urllib.error.HTTPError: If API request fails
+        ValueError: If response is invalid
+    """
+    base_url = "https://financialmodelingprep.com/api/v3/economic_calendar"
+
+    # Build query parameters
+    params = {
+        'from': from_date,
+        'to': to_date,
+        'apikey': api_key
+    }
+
+    # Construct URL with parameters
+    url = f"{base_url}?{urllib.parse.urlencode(params)}"
+
+    try:
+        # Make API request
+        with urllib.request.urlopen(url) as response:
+            if response.status != 200:
+                raise ValueError(f"API returned status code {response.status}")
+
+            data = json.loads(response.read().decode('utf-8'))
+
+            if not isinstance(data, list):
+                raise ValueError(f"Unexpected API response format: {type(data)}")
+
+            return data
+
+    except urllib.error.HTTPError as e:
+        error_body = e.read().decode('utf-8') if e.fp else 'No error details'
+        raise urllib.error.HTTPError(
+            e.url, e.code, f"FMP API error: {e.reason}. Details: {error_body}",
+            e.hdrs, e.fp
+        )
+    except urllib.error.URLError as e:
+        raise ValueError(f"Network error: {e.reason}")
+
+
+def validate_date_range(from_date: str, to_date: str) -> None:
+    """
+    Validate date range is within FMP API limits (max 90 days).
+
+    Args:
+        from_date: Start date in YYYY-MM-DD format
+        to_date: End date in YYYY-MM-DD format
+
+    Raises:
+        ValueError: If date range is invalid or exceeds 90 days
+    """
+    try:
+        start = datetime.strptime(from_date, '%Y-%m-%d')
+        end = datetime.strptime(to_date, '%Y-%m-%d')
+    except ValueError as e:
+        raise ValueError(f"Invalid date format. Use YYYY-MM-DD: {e}")
+
+    if start > end:
+        raise ValueError(f"Start date {from_date} is after end date {to_date}")
+
+    delta = (end - start).days
+    if delta > 90:
+        raise ValueError(f"Date range ({delta} days) exceeds maximum of 90 days")
+
+    # Warn if querying past dates
+    today = datetime.now().date()
+    if end.date() < today:
+        print(f"Warning: End date {to_date} is in the past", file=sys.stderr)
+
+
+def format_event_output(events: List[Dict], output_format: str = 'json') -> str:
+    """
+    Format economic events for output.
+
+    Args:
+        events: List of event dictionaries from FMP API
+        output_format: Output format ('json' or 'text')
+
+    Returns:
+        Formatted string
+    """
+    if output_format == 'json':
+        return json.dumps(events, indent=2, ensure_ascii=False)
+
+    elif output_format == 'text':
+        lines = []
+        lines.append(f"Economic Calendar Events (Total: {len(events)})")
+        lines.append("=" * 80)
+
+        for event in events:
+            lines.append(f"\nDate: {event.get('date', 'N/A')}")
+            lines.append(f"Country: {event.get('country', 'N/A')}")
+            lines.append(f"Event: {event.get('event', 'N/A')}")
+            lines.append(f"Currency: {event.get('currency', 'N/A')}")
+            lines.append(f"Impact: {event.get('impact', 'N/A')}")
+
+            previous = event.get('previous')
+            estimate = event.get('estimate')
+            actual = event.get('actual')
+
+            if previous is not None:
+                lines.append(f"Previous: {previous}")
+            if estimate is not None:
+                lines.append(f"Estimate: {estimate}")
+            if actual is not None:
+                lines.append(f"Actual: {actual}")
+
+            change = event.get('change')
+            change_pct = event.get('changePercentage')
+            if change is not None:
+                lines.append(f"Change: {change}")
+            if change_pct is not None:
+                lines.append(f"Change %: {change_pct}%")
+
+            lines.append("-" * 80)
+
+        return "\n".join(lines)
+
+    else:
+        raise ValueError(f"Unknown output format: {output_format}")
+
+
+def main():
+    """Main execution function."""
+    parser = argparse.ArgumentParser(
+        description='Fetch economic calendar events from FMP API',
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  # Fetch events for next 7 days (default)
+  python get_economic_calendar.py
+
+  # Fetch events for specific date range
+  python get_economic_calendar.py --from 2025-01-01 --to 2025-01-31
+
+  # Provide API key via argument (overrides environment variable)
+  python get_economic_calendar.py --api-key YOUR_KEY_HERE
+
+  # Output as formatted text instead of JSON
+  python get_economic_calendar.py --format text
+
+  # Save output to file
+  python get_economic_calendar.py --output calendar.json
+        """
+    )
+
+    # Date range arguments
+    today = datetime.now().date()
+    default_from = today.strftime('%Y-%m-%d')
+    default_to = (today + timedelta(days=7)).strftime('%Y-%m-%d')
+
+    parser.add_argument(
+        '--from', dest='from_date',
+        default=default_from,
+        help=f'Start date in YYYY-MM-DD format (default: {default_from})'
+    )
+    parser.add_argument(
+        '--to', dest='to_date',
+        default=default_to,
+        help=f'End date in YYYY-MM-DD format (default: {default_to})'
+    )
+
+    # API key argument
+    parser.add_argument(
+        '--api-key', dest='api_key',
+        help='FMP API key (overrides FMP_API_KEY environment variable)'
+    )
+
+    # Output format
+    parser.add_argument(
+        '--format', choices=['json', 'text'],
+        default='json',
+        help='Output format (default: json)'
+    )
+
+    # Output file
+    parser.add_argument(
+        '--output', '-o',
+        help='Output file path (default: stdout)'
+    )
+
+    # Parse arguments
+    args = parser.parse_args()
+
+    # Get API key
+    api_key = args.api_key or get_api_key()
+    if not api_key:
+        print("Error: FMP API key is required. Set FMP_API_KEY environment variable or use --api-key",
+              file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        # Validate date range
+        validate_date_range(args.from_date, args.to_date)
+
+        # Fetch events
+        print(f"Fetching economic calendar from {args.from_date} to {args.to_date}...",
+              file=sys.stderr)
+        events = fetch_economic_calendar(args.from_date, args.to_date, api_key)
+
+        print(f"Retrieved {len(events)} events", file=sys.stderr)
+
+        # Format output
+        output = format_event_output(events, args.format)
+
+        # Write output
+        if args.output:
+            with open(args.output, 'w', encoding='utf-8') as f:
+                f.write(output)
+            print(f"Output written to {args.output}", file=sys.stderr)
+        else:
+            print(output)
+
+        sys.exit(0)
+
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == '__main__':
+    main()

package/.claude/skills/ftd-detector/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: ftd-detector
+description: 检测Follow-Through Day（FTD）信号以确认市场底部，采用William O'Neil的方法论。双指数跟踪（S&P 500 + NASDAQ），使用状态机进行反弹尝试、FTD确认和FTD后健康监控。当用户询问市场底部信号、Follow-Through Day、反弹尝试、调整后的重新入场时机，或是否可以安全增加股票仓位时使用。与market-top-detector（防御性）互补——本技能为进攻性（底部确认）。
+---
+
+# FTD检测器技能
+
+## 目的
+
+检测确认市场底部的Follow-Through Day（FTD）信号，采用William O'Neil经过验证的方法论。生成质量评分（0-100），并提供重新进入市场的仓位建议。
+
+**与Market Top Detector互补：**
+- Market Top Detector = 防御性（检测派发、轮动、恶化）
+- FTD Detector = 进攻性（检测反弹尝试、底部确认）
+
+## 何时使用本技能
+
+**英文：**
+- User asks "Is the market bottoming?" or "Is it safe to buy again?"
+- User observes a market correction (3%+ decline) and wants re-entry timing
+- User asks about Follow-Through Days or rally attempts
+- User wants to assess if a recent bounce is sustainable
+- User asks about increasing equity exposure after a correction
+- Market Top Detector shows elevated risk and user wants bottom signals
+
+**中文：**
+- "市场见底了吗？""可以重新买入了吗？"
+- 调整行情（3%以上的下跌）后的入场时机判断
+- 关于Follow-Through Day或反弹尝试的问题
+- 想要评估近期反弹是否可持续
+- 调整后是否应增加仓位的判断
+- Market Top Detector显示高风险后，确认底部信号
+
+## 与Market Top Detector的区别
+
+| 方面 | FTD Detector | Market Top Detector |
+|------|-------------|-------------------|
+| 关注点 | 底部确认（进攻性） | 顶部检测（防御性） |
+| 触发条件 | 市场调整（3%+下跌） | 市场处于/接近高点 |
+| 信号 | 反弹尝试 → FTD → 重新入场 | 派发 → 恶化 → 退出 |
+| 评分 | 0-100 FTD质量 | 0-100 顶部概率 |
+| 行动 | 何时增加仓位 | 何时减少仓位 |
+
+---
+
+## 执行工作流
+
+### 第一阶段：执行Python脚本
+
+运行FTD检测器脚本：
+
+```bash
+python3 skills/ftd-detector/scripts/ftd_detector.py --api-key $FMP_API_KEY
+```
+
+脚本将执行以下操作：
+1. 从FMP API获取S&P 500和QQQ的历史数据（60+个交易日）
+2. 获取两个指数的当前报价
+3. 运行双指数状态机（调整 → 反弹 → FTD检测）
+4. 评估FTD后的健康状况（派发日、失效、强势趋势）
+5. 计算质量评分（0-100）
+6. 生成JSON和Markdown报告
+
+**API预算：** 4次调用（完全在免费层250次/天的范围内）
+
+### 第二阶段：展示结果
+
+向用户展示生成的Markdown报告，重点说明：
+- 当前市场状态（调整、反弹尝试、FTD已确认等）
+- 质量评分和信号强度
+- 建议的仓位水平
+- 关键观察水平（摆动低点、FTD当日低点）
+- FTD后的健康状况（派发日、强势趋势）
+
+### 第三阶段：情境化指导
+
+根据市场状态提供额外指导：
+
+**如果FTD已确认（评分60+）：**
+- 建议关注处于正确形态的领涨股
+- 参考CANSLIM筛选器寻找候选股票
+- 提醒注意仓位大小和止损
+
+**如果处于反弹尝试阶段（第1-3天）：**
+- 建议耐心等待，不要在FTD之前买入
+- 建议构建观察列表
+
+**如果没有调整：**
+- FTD分析在上升趋势中不适用
+- 转向Market Top Detector获取防御性信号
+
+---
+
+## 状态机
+
+```
+NO_SIGNAL → CORRECTION → RALLY_ATTEMPT → FTD_WINDOW → FTD_CONFIRMED
+                ↑              ↓               ↓              ↓
+                └── RALLY_FAILED ←─────────────┘     FTD_INVALIDATED
+```
+
+| 状态 | 定义 |
+|------|------|
+| NO_SIGNAL | 上升趋势，无符合条件的调整 |
+| CORRECTION | 3%+的下跌，伴随3+个下跌日 |
+| RALLY_ATTEMPT | 从摆动低点开始的第1-3天反弹 |
+| FTD_WINDOW | 第4-10天，等待符合条件的FTD |
+| FTD_CONFIRMED | 检测到有效的FTD信号 |
+| RALLY_FAILED | 反弹跌破摆动低点 |
+| FTD_INVALIDATED | 收盘价低于FTD当日低点 |
+
+## 质量评分（0-100）
+
+| 评分 | 信号 | 仓位 |
+|------|------|------|
+| 80-100 | 强FTD | 75-100% |
+| 60-79 | 中等FTD | 50-75% |
+| 40-59 | 弱FTD | 25-50% |
+| <40 | 无FTD / 失败 | 0-25% |
+
+---
+
+## API要求
+
+**必需：** FMP API密钥（免费层即可：每次执行4次调用）
+
+## 输出文件
+
+- JSON: `ftd_detector_YYYY-MM-DD_HHMMSS.json`
+- Markdown: `ftd_detector_YYYY-MM-DD_HHMMSS.md`
+
+## 参考文档
+
+### `references/ftd_methodology.md`
+- O'Neil的FTD规则详解
+- 反弹尝试机制和天数计算
+- 历史FTD案例（2020年3月、2022年10月）
+
+### `references/post_ftd_guide.md`
+- FTD后派发日失败率
+- 强势趋势（Power Trend）的定义和条件
+- 成功与失败模式对比
+
+### 何时加载参考文档
+- **首次使用：** 加载 `ftd_methodology.md` 以全面理解
+- **FTD后的问题：** 加载 `post_ftd_guide.md`
+- **常规执行：** 无需参考文档——脚本会处理分析

package/.claude/skills/ftd-detector/references/ftd_methodology.md

@@ -0,0 +1,188 @@
+# Follow-Through Day (FTD) Methodology
+
+## Overview
+
+The Follow-Through Day (FTD) is William O'Neil's market timing signal for confirming a new uptrend after a correction. It is the **single most important signal** for re-entering the market after a decline. Without an FTD, no new bull market or sustained rally has ever begun (per IBD historical analysis).
+
+**Key Insight:** FTD is a necessary but not sufficient condition. Historically, approximately 25% of FTDs lead to sustained uptrends. The remaining 75% fail, which is why quality scoring and post-FTD monitoring are critical.
+
+---
+
+## Step 1: Identify the Correction
+
+### Qualifying Correction
+A correction must meet these criteria before FTD analysis begins:
+
+- **Decline magnitude:** Index closes 3% or more below its recent high
+- **Duration:** At least 3 down days during the decline
+- **Index scope:** S&P 500 and/or NASDAQ Composite (either suffices)
+
+### Swing Low Definition
+The swing low is the lowest closing price during the correction that becomes the reference point for the rally attempt:
+
+- Must be preceded by 3%+ decline from a recent high (within 40 trading days)
+- Must have at least 3 down days between the high and the low
+- Must be a local minimum (adjacent days have higher closes)
+- Multiple swing lows can occur; use the most recent qualifying one
+
+**Important:** The swing low is determined by *closing price*, not intraday low.
+
+---
+
+## Step 2: Rally Attempt (Day 1-3)
+
+### Day 1 Detection
+Day 1 marks the beginning of a rally attempt. It occurs on the **first qualifying up day** after the swing low:
+
+**Primary criterion:** Close > Previous day's close (up day)
+
+**Alternative criterion:** Close in the top 50% of the day's price range
+- Formula: (Close - Low) / (High - Low) >= 0.50
+- This captures days where the market recovers significantly from intraday lows even if it doesn't close above the prior day's close
+
+### Day 2-3 Integrity Check
+For the rally attempt to remain valid through Day 2-3:
+
+- **Close must not breach Day 1's intraday low** (not the close, the *low*)
+- This is a strict rule; even a single day closing below Day 1's low invalidates the attempt
+- Day 2 and Day 3 do NOT need to be up days; they just cannot close below Day 1's low
+
+### Rally Invalidation (Reset)
+The rally attempt resets completely if:
+
+1. **Any day's close falls below the swing low price** → Start over from new potential swing low
+2. **Day 2 or Day 3 closes below Day 1's intraday low** → Wait for new Day 1
+
+When a rally resets, the new lower price may become the new swing low, and the cycle begins again.
+
+---
+
+## Step 3: FTD Window (Day 4-10)
+
+### FTD Qualification Criteria
+A Follow-Through Day must satisfy ALL of these conditions:
+
+1. **Day 4-10** of the rally attempt (Day 4-7 is the prime window; Day 8-10 still valid)
+2. **Price gain >= 1.25%** (minimum threshold)
+   - 1.25-1.49%: Minimum qualifying gain
+   - 1.50-1.99%: Recommended gain (higher reliability)
+   - 2.00%+: Strong signal
+3. **Volume > previous day's volume** (mandatory)
+   - This confirms institutional participation
+   - Volume does not need to exceed the 50-day average, though it's a positive if it does
+
+### Day Counting Rules
+- Day 1 = first qualifying up day after swing low
+- Day 2, 3, etc. = every subsequent trading day (regardless of whether it's up or down)
+- Days count continues as long as the rally is not invalidated
+- The FTD itself must be an up day meeting the gain and volume requirements
+
+### Prime vs Late Window
+
+**Day 4-7 (Prime):**
+- Historically higher success rate
+- Base quality score: 60 points
+- Institutional buyers are more likely to have conviction
+
+**Day 8-10 (Late):**
+- Still valid but statistically weaker
+- Base quality score: 50 points
+- May indicate hesitant institutional buying
+
+**After Day 10:**
+- No longer qualifies as a traditional FTD
+- Rally without FTD by Day 10 is a warning sign
+- May still develop into an uptrend but reliability drops significantly
+
+---
+
+## Step 4: Dual-Index Confirmation
+
+### Single-Index FTD
+An FTD on either the S&P 500 or NASDAQ is sufficient to trigger the signal. The signal is actionable on a single-index confirmation.
+
+### Dual-Index FTD
+When both S&P 500 and NASDAQ produce FTDs (within a few days of each other):
+- Significantly higher reliability
+- Quality score bonus: +15 points
+- Indicates broader institutional conviction
+- Both growth and value participants are buying
+
+### Index Discrepancy
+When one index confirms FTD but the other is still in rally attempt or correction:
+- FTD is still valid from the confirming index
+- Monitor the lagging index for convergence or divergence
+- Divergence (one fails while other holds) is a cautionary signal
+
+---
+
+## Quality Score Framework
+
+### Score Components (0-100)
+
+| Factor | Criteria | Points |
+|--------|----------|--------|
+| **Base (FTD Day)** | Day 4-7 | 60 |
+| | Day 8-10 | 50 |
+| **Price Gain** | >= 2.0% | +15 |
+| | >= 1.5% | +10 |
+| | >= 1.25% | +5 |
+| **Volume vs 50-day Avg** | Above average | +10 |
+| | Below average | +0 |
+| **Dual Index Confirm** | Both S&P 500 + NASDAQ | +15 |
+| | Single index | +0 |
+| **Post-FTD Health** | No distribution (5 days) | +10 |
+| | Distribution Day 4-5 | -5 |
+| | Distribution Day 3 | -15 |
+| | Distribution Day 1-2 | -30 |
+
+### Interpretation
+
+| Score | Signal | Recommended Exposure |
+|-------|--------|---------------------|
+| 80-100 | Strong FTD | 75-100% equity |
+| 60-79 | Moderate FTD | 50-75% equity |
+| 40-59 | Weak FTD | 25-50% equity |
+| < 40 | No FTD / Failed | 0-25% equity |
+
+---
+
+## Historical FTD Examples
+
+### March 2020 (COVID Crash)
+- **Swing Low:** March 23, 2020 (S&P 500: ~2,237)
+- **Day 1:** March 24, 2020 (+9.4%)
+- **FTD:** April 2, 2020 (Day 8 of rally, +2.3% on higher volume)
+- **Outcome:** Successful - began one of the strongest bull markets in history
+- **Quality:** Moderate (Day 8 = late window, but strong gain and volume)
+- **Note:** Multiple failed rally attempts preceded this successful one
+
+### October 2022 (Bear Market Bottom)
+- **Swing Low:** October 13, 2022 (S&P 500: ~3,491)
+- **Day 1:** October 14, 2022 (+2.6%)
+- **FTD:** October 21, 2022 (Day 6, +2.4% on higher volume)
+- **Outcome:** Successful - confirmed the end of the 2022 bear market
+- **Quality:** High (Day 6 = prime window, strong gain, above-avg volume)
+
+### June 2022 (Failed FTD)
+- **Swing Low:** June 17, 2022 (S&P 500: ~3,666)
+- **FTD:** Late June 2022
+- **Outcome:** Failed - market made new lows by September 2022
+- **Lesson:** FTD occurred but distribution days followed quickly; market environment (rising rates, inflation) was hostile
+
+### December 2018 (Christmas Eve Low)
+- **Swing Low:** December 24, 2018 (S&P 500: ~2,351)
+- **FTD:** January 4, 2019 (Day 6, +3.4% on higher volume)
+- **Outcome:** Successful - powerful rally through 2019
+- **Quality:** Very high (prime window, strong gain, Fed pivot as catalyst)
+
+---
+
+## Common Mistakes
+
+1. **Buying before FTD confirmation:** Acting on Day 1-3 before FTD is confirmed
+2. **Ignoring volume:** A large gain without volume increase is NOT an FTD
+3. **Counting wrong:** Including non-trading days or resetting day count incorrectly
+4. **Single vs. dual index:** Treating single-index FTD as equivalent to dual-index
+5. **Ignoring post-FTD distribution:** Not monitoring for early distribution days
+6. **FTD ≠ all clear:** Treating FTD as guarantee rather than probability shift