🦅 Kestrel

Local-first Stock Intelligence System for Taiwan + US Markets

A persistent, self-improving AI agent that hunts for explosive growth stocks

---

What is Kestrel?

Kestrel is named for the falcon that hovers still before a precise dive — a personal market intelligence system that combines:

• Multi-factor scoring across Technical · Chip · Fundamental · Theme · Macro dimensions
• 16 chart pattern detectors + 17 candlestick combo patterns + golden combo detection
• Multi-timeframe analysis (intraday → 6-month) for swing trades and position holds
• Dynamic theme system with 148 themes, 3-layer AI classification, real-time heat tracking
• Kestrel agent with memory, skills, investor personas, multi-platform gateway
• Social intelligence — RSS, PTT, policy monitors analyzed by Claude Haiku in real-time
• Backtest engine — event-driven, zero look-ahead bias, auto-fetches historical data on demand
• Multi-source data layer — 5 providers with cache-first routing
• Broker integration — 永豐 (Shioaji) + 元大 (Yuanta) + Interactive Brokers with paper trading

Local-first design. No Docker, no servers, no cloud required. Everything runs on your machine using DuckDB + SQLite + diskcache.

---

Why Kestrel?

Most stock screeners tell you what is moving, but not why it should keep moving — and they treat Taiwan and US markets identically when the alpha sources are completely different.

Kestrel separates them:

Market	Unique Signals
Taiwan	Monthly revenue (MOPS) · TDCC holder count · Institutional flows · Margin/short · Day-trading ratio · Broker concentration · Stock futures OI
US	Options unusual flow · Institutional holders · Insider transactions · Earnings surprises · Short interest
Common	RS Line · Pattern detection (16 detectors) · EPS acceleration · Sector rotation (RRG) · Macro (VIX, yield curve, DXY, Fear & Greed)

---

Key Features

🎯 Multi-Timeframe Detection

• Day (intraday-3day): Episodic Pivot, candlestick combos, RVOL spikes
• Swing (1-3 weeks): Pocket Pivot, Double Bottom, Bull Flag, Triangles, Wedges
• Position (1-3 months): VCP, Cup & Handle, Stage 2, Darvas Box, Flat Base
• Trend (3-12 months): CANSLIM, Three Weeks Tight, growth screening

🌱 Growth Stock Screening (Separate Pipeline)

Revenue growth ≥20%, gross margin expanding, D/E < 1.0, above MA200. Fundamental weight 50%.

🤖 Kestrel Agent

• 4-layer persistent memory: Working + Episodic (FTS5 search) + Semantic + Procedural
• 5 modes: Single, Orchestrated, Personas, Skill, Team
• 16 file-based skills with LLM fallback routing
• 12 agent tools (scoring, chip data, patterns, data queries)
• Multi-platform: Telegram bot + LINE bot + CLI + Web Dashboard
• Investor personas: Buffett, Lynch, Graham, Burry, Druckenmiller
• Multi-provider LLM via OpenRouter (Claude, GPT, Grok, DeepSeek)

📊 Pattern Engine (16 Detectors + 17 Candlestick Combos)

Position patterns: VCP, Cup & Handle, Stage 2 Breakout, Darvas Box, Flat Base, Three Weeks Tight

Swing patterns: Pocket Pivot, Double Bottom, Bull Flag, High Tight Flag, Falling/Rising Wedge, Ascending/Descending/Symmetrical Triangle

Day patterns: Episodic Pivot, Candlestick Combos (8 bullish + 9 bearish)

🌐 Dynamic Theme System

• 148 themes
• 3-layer classification: GICS auto-assign + LLM batch + social reinforcement
• Real-time heat from RSS/PTT/policy monitors

📈 Multi-Source Data Layer

• 5 providers: FinMind, yfinance, Finnhub, Alpha Vantage, FMP
• Cache-first: DuckDB check before any API call
• Fallback chains: If primary fails, auto-try secondary source
• Premium tier: Sponsor-only datasets gated by subscription

💼 Broker Integration

• 永豐金 (SinoPac): Shioaji SDK, cross-platform, paper + live trading
• 元大 (Yuanta): OneAPI via Windows bridge service
• Interactive Brokers: ib_insync, US + TW + global markets
• Multi-broker sessions: Connect all 3 simultaneously, switch active broker
• Safety guards: Position size limits, daily loss circuit breaker, trade count cap
• Audit log: Immutable record of every broker action

🔔 Notifications & Chat

• Telegram bot: Send messages to agent, receive alerts + analysis
• LINE bot: Same as Telegram, via LINE Official Account
• Push alerts: Score threshold triggers → instant notification
• CLI: Full agent access via command line

🛡️ Production-Grade Engineering

• Data quality layer with cross-source validation
• Per-user async locks prevent race conditions
• Tool retry + circuit breaker for resilience
• Edge case handlers (ex-dividend, limit-up, disposition, IPO, wash trading)
• Stealth accumulation detector (7 micro-signals for small caps)
• Cost ceiling + rate limiting for OpenRouter

---

Architecture

┌──────────────────────────────────────────────────────────────────┐
│                    Multi-Source Data Layer                         │
│  FinMind · yfinance · Finnhub · Alpha Vantage · FMP   │
│  Cache-first · Key rotation · Fallback chains · Premium gating   │
└─────────────────────────────┬────────────────────────────────────┘
                              ▼
┌──────────────────────────────────────────────────────────────────┐
│              Local Storage (No Servers Required)                   │
│   DuckDB 1.5 · SQLite + FTS5 · diskcache · Parquet archive       │
└──────────────────┬──────────────────────────┬────────────────────┘
                   ▼                          ▼
┌────────────────────────────┐  ┌─────────────────────────────────┐
│   Analysis Pipeline         │  │   Kestrel Agent  │
│   21 patterns + 17 combos   │  │   ReAct + Memory + 16 Skills    │
│   5-dim scoring + themes    │  │   12 tools + LLM routing        │
│   Sector rotation (RRG)     │  │   Telegram/LINE/CLI/Web gateway │
│   Social intelligence       │  │   Investor personas panel       │
│   Stealth accumulation      │  │   Slash commands + watchlist    │
└────────────┬───────────────┘  └─────────────────────────────────┘
             ▼
┌──────────────────────────────────────────────────────────────────┐
│    Dashboard (Next.js 16) · 3 Themes · i18n (EN + zh-TW)         │
│    Alerts (Telegram/LINE bots) · Broker Trading (永豐/元大/IB)    │
│    Backtest Engine (auto-fetch data · TW+US cost models)          │
└──────────────────────────────────────────────────────────────────┘

→ Full details in docs/ARCHITECTURE.md

---

Tech Stack

• Language: Python 3.12+ (backend) + TypeScript 5 (frontend)
• Backend: FastAPI + uvicorn + APScheduler (75 routes)
• Frontend: Next.js 16 + Tailwind CSS 4 + Recharts + Lightweight Charts
• Storage: DuckDB 1.5 (analytical) + SQLite (operational) + diskcache
• AI/LLM: OpenRouter (multi-model — Claude, GPT, Grok, DeepSeek)
• Broker SDKs: Shioaji (永豐) + ib_insync (IB) + Yuanta bridge (元大)
• Data Sources: FinMind + yfinance + Finnhub + Alpha Vantage + FMP
• Auth: Telegram OIDC + LINE OAuth → JWT sessions
• i18n: next-intl (EN + zh-TW)
• Package Manager: uv (Python) + pnpm (frontend)

---

Quick Start

# 1. Clone
git clone https://github.com/iadr-dev/kestrel.git
cd kestrel

# 2. Install dependencies (Python 3.12+ required)
uv sync

# 3. Configure API keys
cp .env.example .env
# Edit .env: OPENROUTER_API_KEY (required), FINMIND_API_TOKEN (for TW data)
# yfinance works without any key for US data

# 4. Start the API server
uv run uvicorn kestrel.api.main:app --reload --port 8000

# 5. Start the agent (CLI mode)
uv run python -m kestrel.agent.gateway --mode cli

# 6. (Optional) Start the dashboard
cd web && pnpm install && pnpm dev
# Open http://localhost:3000

---

Dashboard

Three themes: Neo-Terminal (dark/cyan) · Tactical HUD (dark/green) · Hermès (light/orange)

Features:

• Ticker tape + 5-tab navigation (Market · Signals · Agent · Trading · Settings)
• RRG scatter chart + theme heatmap + sector rankings
• Signal cards with score arc + K-line chart (TradingView Lightweight Charts)
• Agent chat with tool call cards + mode selector (single/team/debate/personas)
• Portfolio positions + backtest runner + broker connections
• Global search (⌘K) + keyboard shortcuts + i18n toggle

---

Agent Platforms

Platform	How to set up	Capabilities
CLI	python -m kestrel.agent.gateway --mode cli	Full agent + slash commands
Telegram	Create bot via @BotFather → set TELEGRAM_BOT_TOKEN	Chat + push alerts
LINE	Create LINE Official Account → set LINE_CHANNEL_ACCESS_TOKEN	Chat + push alerts
Web	Dashboard at http://localhost:3000/dashboard/agent	Chat + rich rendering

Users message our bot → agent processes → replies in the same chat. Push alerts sent to users based on their notification preferences.

---

Cost Estimate

For personal daily use: ~$3-5/month total:

Component	Monthly Cost
OpenRouter (Claude Sonnet + Haiku)	$3-5
Market data (yfinance, FinMind free, Finnhub free)	$0
Broker paper trading	$0
Optional: Finnhub paid (real-time insider + options)	$49
Optional: FMP paid (30yr financials + screener)	$15

Zero paid dependencies required for core functionality. All market data uses free sources.

---

Documentation

Doc	Content
docs/ARCHITECTURE.md	System architecture index
docs/AGENT-DESIGN.md	Agent system design
docs/API-DOC.md	HTTP API reference (75 endpoints)
docs/API-DESIGN.md	API design decisions + streaming protocol
docs/STRATEGY_GUIDE.md	Strategy & factor guide (EN)
docs/STRATEGY_GUIDE-TW.md	Strategy & factor guide (zh-TW)
docs/references/	Architecture + implementation detail docs

---

Why "Kestrel"?

The kestrel is the falcon that hovers perfectly still before its precise dive — observing patiently, then striking with overwhelming accuracy.

That's the philosophy: don't chase, don't react. Watch the patterns develop, accumulate evidence across multiple dimensions, then strike with conviction when everything aligns.

---

License

AGPL-3.0 — see LICENSE

Disclaimer

Not financial advice. Kestrel is a research and monitoring tool. All trading decisions and consequences are entirely the user's responsibility. Past backtest performance does not guarantee future results.