# 🐋 FinClaw

**AI Trading Engine with Verified Alpha**

**[English](README.md)** | **[中文](docs/README_zh.md)** | **[日本語](docs/README_ja.md)** | **[한국어](docs/README_ko.md)** | **[Français](docs/README_fr.md)**

```
100万 → 354万 (5年, 年化29.1%)
Tested on 100+ real stocks across US, China, Hong Kong
30/34 individual stock backtests outperform market
```

---

## What does it do?

FinClaw scans stocks, picks winners, manages risk, and validates everything with real data.

```bash
# Pick 5 best US stocks with Soros-style momentum strategy
python FinClaw.py scan --market us --style soros --top 5

# Backtest any stock
python FinClaw.py backtest --ticker NVDA --period 5y

# Run full test suite
python FinClaw.py test
```

## Why FinClaw?

Most "AI trading" projects generate signals and stop there. No backtesting, no risk management, no validation.

FinClaw is different:

- **Verified**: Every claim backed by reproducible backtests
- **Complete**: Selection → Entry → Position Management → Exit → Portfolio
- **Tested**: 34 automated regression tests, every commit validated
- **Multi-market**: US stocks, China A-shares, Hong Kong
- **Honest**: We show where we lose, not just where we win

## Performance

### 5-Year Real Data (2020-2025)

| Strategy | Annual Return | 5Y Total | Risk Level |
|----------|:------------:|:--------:|:----------:|
| v10 Unified Top-5 | **+29.1%/y** | +254% | High |
| LLM-Enhanced Top-10 | +24.8%/y | +202% | Medium-High |
| Balanced Top-10 | +19.5%/y | +142% | Medium |
| Conservative Top-15 | +11.8%/y | +74% | Low |

*Tested on 100+ real stocks from Yahoo Finance. No synthetic data.*

### Individual Stock Win Rate

Tested head-to-head against AHF's technical analysis on 34 stocks:

```
FinClaw wins: 30/34 (88%)
Average edge: +10.8% per year
```

## Quick Start

### 1. Install

```bash
git clone https://github.com/user/FinClaw.git
cd FinClaw
pip install -r requirements.txt  # aiohttp, yfinance
```

### 2. Verify

```bash
python FinClaw.py test
# Expected: 34/34 tests passed
```

### 3. Pick Stocks

```bash
# US market, aggressive style
python FinClaw.py scan --market us --style druckenmiller

# China A-shares, balanced
python FinClaw.py scan --market china --style buffett

# All markets
python FinClaw.py scan --market all --style soros
```

### 4. Backtest

```bash
python FinClaw.py backtest --ticker NVDA --period 5y
python FinClaw.py backtest --ticker 688256.SS --period 3y
```

## 8 Built-in Strategies

| Strategy | Philosophy | Risk | Target |
|----------|-----------|:----:|:------:|
| `druckenmiller` | Momentum. "When you see it, bet big." | Very High | 25-40%/y |
| `soros` | Reflexivity. Self-reinforcing trends. | High | 25-35%/y |
| `cathie_wood` | Disruptive innovation. 5-year horizon. | Very High | 20-40%/y |
| `buffett` | Quality + value. Buy fear, hold forever. | Medium | 20-30%/y |
| `lynch` | Growth/volatility ratio. "Boring" winners. | Medium | 20-27%/y |
| `simons` | Pure quant. Highest Sharpe ratio. | Medium | 15-25%/y |
| `dalio` | All-weather. Low correlation, risk parity. | Low | 12-18%/y |
| `conservative` | Low-vol blue chips. Capital preservation. | Very Low | 8-12%/y |

## How It Works

```
┌──────────────────────────────────────────────────────┐
│                    FinClaw v10                     │
│                                                        │
│  1. SCAN        Multi-factor + AI disruption analysis  │
│  2. RANK        7 master strategies vote               │
│  3. SELECT      Top-N by conviction score              │
│  4. ENTER       Regime-adaptive timing (7 regimes)     │
│  5. MANAGE      Trailing stop + pyramiding + sizing    │
│  6. EXIT        Regime shift + trend breakdown          │
│  7. VALIDATE    34 TDD tests + real data backtest      │
│                                                        │
│  Selection engine: 3 layers                            │
│  ┌─────────┐ ┌──────────────┐ ┌──────────────────┐   │
│  │ Quant   │+│ Fundamentals │+│ AI Disruption    │   │
│  │ 6 factor│ │ P/E, growth  │ │ Who wins in AI?  │   │
│  └─────────┘ └──────────────┘ └──────────────────┘   │
└──────────────────────────────────────────────────────┘
```

### Selection Engine (3 Layers)

**Layer 1 — Quantitative (always on)**
- Multi-timeframe momentum (1M/3M/6M/1Y)
- EMA trend alignment (8/21/55)
- RSI, Bollinger Bands, volume confirmation
- Sharpe ratio, max drawdown, volatility

**Layer 2 — Fundamental (yfinance)**
- P/E, P/B, PEG ratio
- Revenue growth, profit margins
- Return on equity, debt ratios

**Layer 3 — AI Disruption Analysis**
- Is this company an AI winner or victim?
- Competitive moat in the AI era
- Narrative strength (self-reinforcing?)
- Example: NVIDIA (+0.25 boost) vs Salesforce (-0.21 penalty)

### Signal Engine (7 Regimes)

| Regime | Max Position | Strategy |
|--------|:-----------:|----------|
| CRASH | 0% | Emergency exit |
| STRONG_BEAR | 10% | Defensive bounces only |
| BEAR | 15% | Small counter-trend |
| RANGING | 45-68% | Mean reversion |
| VOLATILE | 65% | Direction-dependent |
| BULL | 80% | Trend following |
| STRONG_BULL | 92% | Maximum conviction |

## Project Structure

```
FinClaw/
├── FinClaw.py              # CLI entry point
├── agents/
│   ├── signal_engine_v7.py     # 6-factor signal engine
│   ├── backtester_v7.py        # Full lifecycle backtester
│   ├── stock_picker.py         # Multi-factor stock picker
│   ├── llm_analyzer.py         # AI disruption analysis
│   ├── ahf_simulator.py        # Competitor simulator
│   └── statistics.py           # Sharpe, drawdown, etc.
├── tests/
│   └── test_engine.py          # 34 regression tests
├── benchmark_v10.py            # Unified engine benchmark
├── benchmark_multimarket.py    # Global market test
├── benchmark_real.py           # Real data validation
├── docs/
│   ├── README_zh.md            # 中文文档
│   ├── README_ja.md            # 日本語ドキュメント
│   ├── README_ko.md            # 한국어 문서
│   └── README_fr.md            # Documentation française
└── _scratch/                   # Archived experiments
```

## Development

### Run Tests

```bash
python FinClaw.py test
# or directly:
python tests/test_engine.py
```

### Test Coverage

| Test | What it checks |
|------|---------------|
| Golden Thresholds | 9 scenarios must meet minimum alpha |
| Average Alpha | Portfolio average must exceed 9% |
| No Catastrophic Loss | No single trade > 35% loss |
| Regime Detection | Bull/bear/ranging correctly identified |
| Determinism | Same input → same output |
| Warmup Protection | No trades in first 20 bars |
| vs Freqtrade | Must beat on all 9 sim scenarios |

### Contributing

```bash
# 1. Make your change
# 2. Run tests (must pass all 34)
python tests/test_engine.py
# 3. Run quick benchmark
python benchmark_real.py
# 4. If alpha improved or neutral, submit PR
```

## Roadmap

### Done ✅
- [x] 6-factor signal engine with 7 regimes
- [x] Full lifecycle backtester
- [x] Multi-factor stock picker (quant + fundamental)
- [x] AI disruption analysis layer
- [x] 7 master strategy presets
- [x] CLI with one-command scanning
- [x] 34 TDD regression tests
- [x] Multi-market support (US, China, HK)
- [x] Multi-language docs (EN, ZH, JA, KO, FR)

### Next 🔨
- [ ] Live market data streaming
- [ ] Paper trading mode
- [ ] Web dashboard
- [ ] Telegram/WeChat alert bot
- [ ] QuantStats HTML report integration
- [ ] Options/futures support
- [ ] Walk-forward validation

## FAQ

**Q: Is this financial advice?**
A: No. This is a research tool. Use at your own risk.

**Q: Can it trade automatically?**
A: Not yet. Currently analysis and backtesting only. Live trading is on the roadmap.

**Q: How is this different from ai-hedge-fund?**
A: AHF generates signals. FinClaw is a complete system — it selects, enters, manages, exits, and validates. We beat AHF on 88% of stocks tested.

**Q: What data does it need?**
A: Just an internet connection. Uses Yahoo Finance (free) for price data.

**Q: Can I add my own stocks?**
A: Yes. Any ticker supported by Yahoo Finance works.

## License

MIT License. Not financial advice. Past performance does not guarantee future results.

---

*Built by an engineer who believes trading systems should be engineered, not hoped.* 🐋
