Market Candlestick & AI Pattern Scanner (`yfinance-ta-patterns`)

High-performance Python library, CLI, and Native MCP Server (yfinance-ta-mcp) that downloads multi-asset market data via yfinance, detects TA-Lib candlestick patterns, and enriches raw signals using an AI/Quant Confluence Engine to generate multi-factor confluence scores (deterministic quantitative confluence heuristic, not uncalibrated win-rate probability), trade setups, and LLM-ready market briefs.

Verified on CPython 3.8 through 3.15 and free-threaded No-GIL CPython 3.14t. Linux x86_64 is the primary target (full test suite); the CI matrix also runs Windows and macOS. On these CPython versions the package installs from PyPI with zero compilation. PyPy 3.8-3.12 and CPython 3.16 (development) get only the dependency-free subset from PyPI (yfinance, pandas and numpy are excluded there by environment markers); see the compatibility matrix below for the exact scope.

🤝 Community, Issues & Support

🎬 Featured on Video: In-depth walkthrough by Context Unfiltered (Tech & Science): "New Python Library Combines Candlestick Patterns With AI" — Watch on Instagram Reels

🐛 Found a bug or calculation issue? Please Open an Issue — reports are tracked and resolved quickly!

💬 Questions, strategies, or feature requests? Join the conversation in GitHub Discussions.

⭐ Find this project useful? Give it a star on GitHub — it helps more traders and quants discover the tool!

☕ Support development (USDT TRC-20): TDVbEdnpgNgoAhNcn1EwXxWHiR3RKLit5P (Verify on TronScan)

Key Features

Multi-Asset Data Loader: Universal fetching and candle normalization for stocks (AAPL, NVDA), crypto (BTC-USD), commodities (GC=F), indices (^GSPC), and forex pairs (EURUSD). Supports custom date ranges (start, end), timezone conversion, UTC-anchored 4h resampling, and raw OHLC integrity validation.
TA-Lib Pattern Detection: Full recognition engine across all 61 canonical TA-Lib candlestick patterns via native C TA-Lib OR built-in pure-Python / NumPy fallback engine (all 61 patterns supported in both modes!).
AI Pattern Confluence Scorer: Multi-factor confluence score ($0.0 - 1.0$) evaluating quantitative confluence (deterministic heuristic, not win-rate probability):
- Multi-EMA trend alignment (20, 50, 200 EMA) with safe warm-up handling
- Zero-lookahead Relative Volume surge (RVOL)
- Canonical Wilder's RSI (14) momentum exhaustion & divergence
- Canonical Wilder's ATR (14) volatility expansion & candle body dominance
Automated Trade Setups: Computes entry price, ATR-based invalidation stop-loss, and multi-tier take-profit targets (1.5x / 3.0x risk/reward).
AI Market Analyst & LLM Integration: Generates executive markdown briefs, JSON payloads, and engineered reasoning prompts tailored for frontier AI agents and reasoning models (Claude 3.7 Sonnet, OpenAI o3-mini / o1, DeepSeek-R1 / V3, Gemini 2.5 Flash / Pro, GPT-4.5, Ollama).
Quantitative Pattern Ranking & Backtesting: Unbiased next-open execution (Open[i+1]), symmetric Long/Short trading, universal FX quote-currency conversion, transaction cost modeling (commissions & slippage), overfitting filters (min_signals), and periodic Sharpe ratio accounting for non-trading hold periods.

🧩 Compatibility & Runtime Verification Matrix

Runtime / Implementation	Versions	Execution Mode	Status	Notes & Verification Scope
CPython (Standard)	3.8, 3.9, 3.10, 3.11, 3.12, 3.13, 3.14, 3.15	Standard bytecode + GIL	✅ Verified	Direct PyPI install (`pip` / `uv`), zero C build required. Full suite in the Linux CI matrix for 3.8-3.15; 3.15 is also smoke-tested on Windows in CI. CPython 3.16 (development build in CI) runs only the dependency-free subset of the suite.
CPython (Free-Threaded)	3.14t	Multi-core No-GIL (PEP 703)	✅ Verified	`yfinance-ta-patterns`, NumPy and pandas run without the GIL (full suite on Linux x86_64, smoke test on Windows in CI). `import yfinance` (via `lxml`) turns the GIL back on unless Python is started with `PYTHON_GIL=0` / `-X gil=0`.
CPython (Free-Threaded)	3.13t	Multi-core No-GIL (PEP 703)	⚠️ Wheels-only install	Plain `pip` / `uv` installs fail: the latest `yfinance` pulls in `curl-cffi` -> `cffi`, which refuses to build on free-threaded 3.13 (`CFFI does not support the free-threaded build of CPython 3.13`). A wheels-only resolution (`uv ... --no-build`) falls back to `yfinance` 0.2.57 and works: the full suite passes (602 tests) with the GIL disabled. Live downloads with that old `yfinance` are not verified; use 3.14t for current `yfinance`.
PyPy (JIT Accelerated)	3.8, 3.9, 3.10, 3.11, 3.12	High-speed JIT tracing	⚠️ Manual setup	On PyPy, PyPI installs only the pure-Python dependencies; `yfinance`, `pandas` and `numpy` must be provided separately. PyPI has no PyPy wheels for `pandas` (in any release) or for current `curl-cffi`, so they must be compiled or taken from prebuilt wheels (the project CI uses wheels it builds itself; PyPy 3.12 runs the dependency-free subset only). Once they are present, the pure-Python engine supports all 61 TA-Lib patterns.
Operating Systems	Linux x86_64, Windows, macOS	Native wheels & source	✅ Verified	Primary target: Linux x86_64 (full suite). CI also runs GitHub's `windows-latest` and `macos-latest` runners. Linux ARM64 and Intel Macs are not covered by CI.

Quick start

1. Installation

yfinance-ta-patterns installs in seconds with zero C build requirements by default, using an internal vectorized pure-Python/NumPy engine for candlestick pattern recognition.

🚀 Quick Installation by Platform

Platform / Tool	Command	Description
Conda / Mamba	`conda install -c conda-forge yfinance-ta-patterns`	Recommended for Quant, Finance & Data Science
Conda + Native TA-Lib	`conda install -c conda-forge yfinance-ta-patterns ta-lib`	Full C-accelerated TA-Lib with zero compilation
Pixi	`pixi add yfinance-ta-patterns`	Modern high-speed reproducible Conda workflow
Ubuntu / Debian (APT PPA)	`curl -sS https://eminsk.github.io/ppa/setup.sh \| sudo bash` `sudo apt install python3-yfinance-ta-patterns`	Official PPA repository (pure apt, zero URLs)
Ubuntu / Debian (.deb)	`sudo apt install ./python3-yfinance-ta-patterns_0.3.67-1_all.deb`	Native `.deb` package from Releases
Ubuntu / Debian (pipx)	`sudo apt install pipx && pipx install yfinance-ta-patterns`	Isolated global CLI tool install (PEP 668 compliant)
uv (Python)	`uv add yfinance-ta-patterns`	Sub-second pure Python installation
pip (Python)	`pip install yfinance-ta-patterns`	Universal PyPI installation

Option A: Using `uv` (Fastest & Recommended)

# 1. Standard install (100% Autonomous AI + Pattern Engine, zero C compiler or Scikit-Learn required):
uv add yfinance-ta-patterns

# 2. Optional: bare-metal AVX2+FMA SIMD matrix acceleration (pre-compiled binary wheels on Windows x64; source build via --no-binary or NumPy fallback on Linux/macOS):
uv add "yfinance-ta-patterns[gemm]"

# 3. Optional: with C TA-Lib extension if you already have local C headers:
uv add "yfinance-ta-patterns[talib]"

# 4. Instant execution without installing into environment:
uvx --from yfinance-ta-patterns yftp --all-patterns --symbol AAPL --timeframe 1h --ai

Tip

Why --no-config? Passing --no-config tells uv to ignore any local or parent uv.toml settings (such as local wheel registries or find-links overrides), ensuring a clean, isolated, and reproducible installation directly from PyPI in any project directory.

Important

⚡ Free-Threaded Python / No-GIL Guide (PEP 703: 3.14t verified, 3.13t wheels-only)

Python 3.13+ introduces experimental free-threaded (No-GIL) builds. yfinance-ta-patterns is verified under free-threaded CPython 3.14t (full suite on Linux x86_64, smoke test on Windows in CI). Here is what you need to know for a smooth No-GIL setup on Windows:

1. Python Version Selection & Wheel Availability

Python 3.14t (Recommended): Verified in No-GIL execution. yfinance-ta-patterns, NumPy, and pandas run with the GIL disabled. Note: yfinance is imported lazily when market data is first loaded, and it pulls in lxml, which has not declared free-threading support, so CPython re-enables the GIL (with a RuntimeWarning) at that point. Start Python with PYTHON_GIL=0 / -X gil=0 to keep it disabled at your own risk, or skip yfinance and pass your own OHLCV DataFrames.
Python 3.13t (wheels-only install): plain pip / uv installs fail, because the latest yfinance pulls in curl-cffi -> cffi, which refuses to build on free-threaded 3.13 (CFFI does not support the free-threaded build of CPython 3.13). A wheels-only install (uv ... --no-build) resolves to yfinance 0.2.57, which predates curl-cffi, and works: the full suite (602 tests) passes with the GIL disabled. Live downloads with that old yfinance are not verified, so prefer 3.14t for current yfinance.

2. Understanding Automatic GIL Re-Enablement

In free-threaded interpreters, sys._is_gil_enabled() may return True for two common reasons:

Global Environment Variable: A Windows user/system variable PYTHON_GIL=1 forces the GIL on at startup. Check in PowerShell:
```
[System.Environment]::GetEnvironmentVariable('PYTHON_GIL', 'User')
```
PEP 703 C-Extension Protection: When loading C extensions (such as talib._ta_lib or third-party network libraries) that have not yet declared Py_MOD_GIL_NOT_USED, CPython automatically re-enables the GIL to protect thread safety and emits a RuntimeWarning.

3. Running in True No-GIL Mode

To run at full multi-core performance with the GIL disabled:

Command Line Flag:
```
python -X gil=0 my_scanner.py
```

PowerShell:

$env:PYTHON_GIL = "0"
python my_scanner.py

CMD:
```
set PYTHON_GIL=0
python my_scanner.py
```
Pure-Python Engine: When native TA-Lib is not installed, the built-in NumPy fallback engine keeps the GIL disabled out-of-the-box without extra flags.

4. Verification

Run yftp --check-talib to inspect the runtime environment:

yftp --check-talib

Or verify programmatically:

from yfinance_ta_patterns import is_freethreaded, is_gil_enabled
print("Free-Threaded build:", is_freethreaded())
print("GIL active:", is_gil_enabled())

Option B: Using Standard `pip`

# Standard install (pure-Python fallback by default):
pip install yfinance-ta-patterns

# Optional: With native C TA-Lib acceleration (requires ta-lib C headers):
pip install "yfinance-ta-patterns[talib]"

Option C: Native C TA-Lib on Linux & macOS (Optional)

Note

Native C TA-Lib is 100% OPTIONAL: yfinance-ta-patterns already includes a built-in high-speed vectorized NumPy pattern recognition engine that works immediately with zero compilation.

If you want the full C-accelerated TA-Lib engine without any manual compilation:

Via Conda (Recommended — Zero C builds):

conda install -c conda-forge yfinance-ta-patterns ta-lib

Or manual C compiler build from source:

macOS (Homebrew):

brew install ta-lib
export TA_INCLUDE_PATH="$(brew --prefix)/include"
export TA_LIBRARY_PATH="$(brew --prefix)/lib"
uv pip install ta-lib

Linux (Ubuntu / Debian / Arch):

# Ubuntu / Debian:
sudo apt-get update && sudo apt-get install -y libta-lib0 libta-lib-dev
# Arch Linux:
yay -S ta-lib

# Then install the python wrapper:
uv pip install ta-lib

🐍 Python Version Compatibility Matrix

Python Version	Execution Mode	Verification Status	Scope & Recommendation
Python 3.15	Standard (GIL)	✅ Verified	Full suite verified on Linux x86_64 (3.15.1); Windows smoke test in CI; not yet covered on macOS.
Python 3.14t	Free-Threaded (No-GIL)	✅ Verified	Core library, NumPy, and pandas run with the GIL disabled; `import yfinance` re-enables it unless `PYTHON_GIL=0` or `-X gil=0` is set.
Python 3.14	Standard (GIL)	✅ Verified	Full verified installation; instant universal PyPI install.
Python 3.13t	Free-Threaded (No-GIL)	⚠️ Wheels-only	Plain `pip` / `uv` installs fail (`cffi` does not support free-threaded 3.13); `uv ... --no-build` falls back to `yfinance` 0.2.57 and the full suite passes with the GIL disabled. Live downloads with that version are not verified.
Python 3.13	Standard (GIL)	✅ Verified	Full verified installation.
Python 3.8–3.12	Standard (GIL)	✅ Verified	Verified on Linux, Windows and macOS in CI (3.8, 3.9 and 3.10 are at or past upstream end-of-life as of October 2026). Includes dedicated pandas 2.3.x index concurrency tests.
PyPy 3.8–3.12	JIT Accelerated	⚠️ Manual setup	PyPI installs only the pure-Python dependencies on PyPy and has no PyPy wheels for `pandas` (in any release) or current `curl-cffi`: `yfinance`, `pandas` and `numpy` must be compiled or taken from prebuilt wheels. Once they are present, the pure-Python engine supports all 61 patterns.

🤖 Native MCP (Model Context Protocol) Server

Connect yfinance-ta-patterns directly to Claude Code, Antigravity, Claude Desktop, Cursor, or Windsurf via the built-in yfinance-ta-mcp JSON-RPC 2.0 server (ta_scan_symbol, ta_scan_watchlist, ta_backtest_patterns, ta_list_patterns, ta_get_economic_calendar, ta_get_news):

Latest Protocol Spec (2025-11-25): Full MCP lifecycle version negotiation supporting 2024-11-05, 2025-03-26, 2025-06-18, and 2025-11-25.
Institutional Tool Metadata: Includes human-readable title, annotations (readOnlyHint: true, openWorldHint), and detailed JSON outputSchema for every tool.
Token-Optimized Output: Emits raw UTF-8 without token-wasting \uXXXX escaping for Cyrillic and currency symbols (€, £, ¥). ta_scan_watchlist features compact: true by default to comfortably remain below Claude Code's 10,000-token tool output threshold.
Verified Macro Calendar: ta_get_economic_calendar retrieves live macroeconomic events mapped to asset currencies with explicit UTC timestamps, returning clean source: "unavailable" when feeds are offline (zero mock/hallucinated macroeconomic data).
Market News Headlines: ta_get_news retrieves recent financial market headlines, publisher attribution, and publication timestamps directly for the selected ticker symbol with resilient fallback handling.

Option 1: Claude Code CLI

# Recommended: install once as a global tool (~0.4s instant startup, avoids uvx cold timeouts)
uv tool install yfinance-ta-patterns
claude mcp add yfinance-ta -- yfinance-ta-mcp

# Or zero-install execution via uvx (pinned version recommended for reproducibility):
claude mcp add yfinance-ta -- uvx --from "yfinance-ta-patterns>=0.3.49" yfinance-ta-mcp

Option 2: Antigravity / Claude Desktop / Cursor / Windsurf (`mcp_config.json`)

{
  "mcpServers": {
    "yfinance-ta": {
      "command": "yfinance-ta-mcp"
    }
  }
}

Or zero-install via uvx:

{
  "mcpServers": {
    "yfinance-ta": {
      "command": "uvx",
      "args": ["--from", "yfinance-ta-patterns", "yfinance-ta-mcp"]
    }
  }
}

🚀 Ready-to-Use Examples (`examples/`)

The repository includes production-ready backtesting and real-time scanning scripts in the examples/ directory:

1. Multi-Pair Historical Backtesting (`examples/multi_pair_backtest.py`)

A rigorous multi-pair portfolio backtest across 6 major and cross Forex pairs (EURUSD, GBPUSD, USDJPY, AUDUSD, EURGBP, EURJPY) over 2 years on hourly (1h) candles.

Key capabilities demonstrated:

Unbiased Execution: Fills trades at Open[i+1] (next candle open) to eliminate lookahead bias.
Fixed Holding Period (holding_period=5): Automatically closes trades after 5 bars. Essential for single-direction candlestick patterns (Hammer, Inverted Hammer, 3 White Soldiers) which otherwise hold positions indefinitely without reverse exit signals.
Universal Forex PnL & Position Sizing: Automatic base-currency normalization for USD-base pairs (USDJPY) and cross-rates (EURGBP), applying commissions in account currency ($0.05 ECN micro-lot).
Composite Scoring: Ranks combinations by combining Win Rate, Profit Factor, Sharpe Ratio, and logarithmic trade volume.

# Run with Python:
python examples/multi_pair_backtest.py

# Or run with uv:
uv run examples/multi_pair_backtest.py

Sample Output:

==================================================================================================
 TOP-10 BEST COMBINATIONS (PAIR + PATTERN) OVER 2y:
==================================================================================================
  Pair        Pattern  Signals WinRate TotalPnL  ProfitFactor  Sharpe  MaxDD MaxDD_%
EURJPY INVERTEDHAMMER       82   63.0%  $+55.34          2.55    0.38  $7.11   0.07%
EURJPY    MORNINGSTAR       46   63.0%  $+21.49          2.66    0.34  $2.87   0.03%
EURUSD         INNECK       12   75.0%   $+6.31          3.81    0.25  $1.14   0.01%
EURUSD STALLEDPATTERN       26   65.4%  $+23.44          3.09    0.29  $5.17   0.05%
EURUSD  STICKSANDWICH        8   62.5%   $+8.13          5.01    0.22  $1.00   0.01%
EURUSD         ONNECK       11   63.6%  $+11.53          4.44    0.17  $1.97   0.02%
USDJPY    MATCHINGLOW      195   55.6%  $+50.36          1.40    0.24 $15.09   0.15%
EURJPY GRAVESTONEDOJI      226   52.4%  $+58.74          1.44    0.24 $20.81   0.21%
EURJPY        HIKKAKE     1604   52.7%  $+50.97          1.06    0.09 $75.80   0.76%
USDJPY       BELTHOLD     1596   47.7%  $+78.87          1.09    0.13 $83.89   0.84%

Full ranked report saved to: all_pairs_ranked.csv

2. Live Multi-Asset Signal Scanner (`examples/live_signals_scanner.py`)

Scans a 12-asset watchlist across Forex and Cryptocurrencies (BTC-USD, ETH-USD) for active candlestick patterns over recent candles, scoring each opportunity with the AI Confluence Engine.

Key capabilities demonstrated:

AI Confluence Scoring: Quantifies trend alignment (EMA 20/50/200), volume expansion, and Wilder RSI (14) momentum into a 0–100% confidence score.
Automated Trade Setups: Calculates exact Entry Price, ATR-based Stop Loss, and Take Profit targets (1:1.5 Risk/Reward ratio).
Automated Opportunity Ranking: Sorts all live setups and highlights the TOP-1 Highest Confidence Trade Setup.

# Run with Python:
python examples/live_signals_scanner.py

# Or run with uv:
uv run examples/live_signals_scanner.py

Sample Output:

=========================================================================================================
 SIGNALS FOUND: 26 (Ranked by AI Confluence / Quality)
=========================================================================================================
       Time  Symbol Direction        Pattern Confluence     Grade        Entry     StopLoss  TakeProfit_1 Risk_Reward          Trend
08.09 19:00 ETH-USD       BUY 3WHITESOLDIERS   80.0/100 EXCELLENT  2499.389893  2483.227621   2523.633300       1:1.5        BULLISH
08.09 17:00  EURUSD       BUY 3WHITESOLDIERS   70.0/100    STRONG     1.163332     1.162101      1.165178       1:1.5 STRONG_BULLISH
08.09 17:00  USDCAD      SELL     HANGINGMAN   70.0/100    STRONG     1.377840     1.378940      1.376190       1:1.5 STRONG_BEARISH

**********************************************************
 TOP-1 SIGNAL: ETH-USD — BUY (3WHITESOLDIERS)
 Candle Time: 08.09 19:00 | Confluence: 80.0/100 [EXCELLENT] (deterministic heuristic, not win probability)
 Market Trend: BULLISH | RSI: 56.3
 Entry Price: 2499.39
 Stop Loss:   2483.23
 Take Profit: 2523.63 (R:R 1:1.5)
**********************************************************

2. Run CLI

# 1. Multi-Currency Portfolio Scanner (automatically scans all 56 Forex pairs without specifying --symbol):
yftp --timeframe 5m --period 30d --all-patterns --ai-analyst

# 2. Or explicitly scan all 56 pairs with custom confluence threshold:
yftp --all-pairs --timeframe 1h --period 60d --ai --min-confidence 0.60

# 3. Scan a custom comma-separated portfolio of symbols:
yftp --symbol EURUSD,GBPUSD,USDJPY --timeframe 15m --ai

# 4. Single symbol AI-scored analysis with Executive Brief:
yftp --symbol GBPUSD --timeframe 5m --period 30d --all-patterns --ai-analyst

# 5. Detect a single pattern with classic output:
yftp --pattern HAMMER --symbol AAPL --timeframe 1h --period 60d

# 6. Generate an LLM-ready prompt template for Frontier Reasoning Models (Claude 3.7 Sonnet / o3-mini / DeepSeek-R1):
yftp --all-patterns --symbol EURUSD --timeframe 1h --period 60d --prompt

CLI Reference

yfinance-ta-patterns [-h] [-v] (--pattern PATTERN | --all-patterns | --mcp | --calendar | --news | --backtest)
                     [--symbol SYMBOL] [--all-pairs] [--period PERIOD] [--timeframe TIMEFRAME]
                     [--lookback-bars LOOKBACK_BARS] [--date YYYY-MM-DD] [--start-date YYYY-MM-DD] [--end-date YYYY-MM-DD]
                     [--execution {next_open,close}] [--min-signals MIN_SIGNALS]
                     [--commission COMMISSION] [--slippage SLIPPAGE] [--auto-adjust]
                     [--ai] [--min-confidence MIN_CONFIDENCE]
                     [--ai-analyst] [--prompt] [--format {text,json,markdown}]

Options

Flag	Description
`-v`, `--version`	Show package version.
`--mcp`	Launch the native JSON-RPC 2.0 Model Context Protocol (MCP) server over stdio.
`--pattern`	Single candlestick pattern (e.g. `HAMMER`, `DOJI`, `CDLKICKING`).
`--all-patterns`	Scan and display signals for all available candlestick patterns.
`--symbol`	Ticker symbol(s) (e.g. `AAPL`, `NVDA`, `BTC-USD`, `EURUSD`). Supports space- or comma-separated lists and positional arguments.
`--all-pairs`	Scan all 56 major, minor, and exotic Forex currency pairs.
`--period`	History period (`5d`, `60d`, `1y`, `max`).
`--timeframe`	Interval alias (`M1`, `M5`, `M15`, `M30`, `H1`, `H4`, `D1`) or `yfinance` interval (`1m`, `5m`, `15m`, `1h`, `4h`, `1d`).
`--lookback-bars`	Number of recent historical bars to inspect for signals (default: `5`).
`--date`	Filter signals for a specific date (`YYYY-MM-DD`).
`--start-date` / `--end-date`	Date range filter (`YYYY-MM-DD`).
`--calendar`	Fetch and display high/medium impact macro economic calendar releases.
`--news`	Fetch and display real-time market news for the symbol.
`--backtest`, `--test`	Run institutional quantitative pattern ranking backtest.
`--execution`	Execution timing: `next_open` (unbiased, enters on bar i+1) or `close` (legacy).
`--min-signals`	Minimum signal count required for ranking (reduces overfitting from 1-trade samples).
`--commission`	Fixed transaction cost per round-trip trade in backtester.
`--slippage`	Slippage in price units applied adversely to entries and exits.
`--auto-adjust`	Enable dividend and split adjustments (recommended for long multi-year stock backtests).
`--ai`	Enrich detected patterns with AI confidence scoring, signal grade, and trade setups.
`--min-confidence`	Minimum confidence threshold for AI scoring ($0.0$ to $1.0$, default: $0.0$ in single mode, $0.55$ in multi-symbol mode).
`--ai-analyst`	Run executive AI market analysis with synthesis and trade setups.
`--prompt`	Generate an LLM prompt ready to pass to ChatGPT, Claude, or local LLMs.
`--format`	Output format: `text` (default), `json`, or `markdown`.

Python API

1. Universal Multi-Asset Data Loader (`MarketDataLoader`)

Fetches and normalizes OHLC data across equities, crypto, forex, and commodities:

from yfinance_ta_patterns import MarketDataLoader

# Stocks
loader = MarketDataLoader(symbol="NVDA", period="60d", interval="1h")
df = loader.get_data()

# Crypto
crypto_loader = MarketDataLoader(symbol="BTC-USD", period="30d", interval="15m")
crypto_df = crypto_loader.get_data()

# Forex (ForexDataLoader is fully compatible alias)
from yfinance_ta_patterns import ForexDataLoader

forex_loader = ForexDataLoader(symbol="EURUSD", period="60d", interval="1h")
forex_df = forex_loader.get_data()

2. AI Pattern Confidence Scorer (`AIPatternScorer`)

Evaluates technical confluence (trend, momentum, volume, volatility) and builds complete risk-managed trade setups:

from yfinance_ta_patterns import MarketDataLoader, AIPatternScorer

# Use period="2y" (or >= 200 daily candles) to ensure complete EMA200 indicator warm-up
data = MarketDataLoader("AAPL", period="2y", interval="1d").get_data()

scorer = AIPatternScorer(data)
scored_signals = scorer.score_all_active(min_confidence=0.60)

for sig in scored_signals:
    print(f"Pattern: {sig.pattern_name}")
    print(f"Confidence: {sig.confidence * 100:.1f}% ({sig.grade.value})")
    print(f"Action: {sig.action}")
    if sig.setup:
        print(f"Entry: {sig.setup.entry_price:.2f}")
        print(f"Stop Loss: {sig.setup.stop_loss:.2f}")
        print(f"Target 1: {sig.setup.take_profit_1:.2f} (R:R {sig.setup.risk_reward_ratio:.1f})")
    print("Confluences:", ", ".join(sig.confluences))
    print("-" * 40)

3. AI Market Analyst & LLM Prompting (`AIMarketAnalyst`)

Generates structured briefs and prompt templates for external LLM reasoning agents:

from yfinance_ta_patterns import MarketDataLoader, AIMarketAnalyst

data = MarketDataLoader("BTC-USD", period="30d", interval="4h").get_data()

analyst = AIMarketAnalyst(data, symbol="BTC-USD")
results = analyst.analyze(min_confidence=0.65)

# 1. Executive Markdown Brief
brief = analyst.generate_brief(results)
print(brief)

# 2. Prompt for Frontier Reasoning Models (Claude 3.7 Sonnet / o3-mini / DeepSeek-R1 / Gemini 2.5)
llm_prompt = analyst.to_llm_prompt(results)

# 3. JSON Payload for APIs / Microservices
json_data = analyst.to_json(results)

4. Quantitative Backtesting & Pattern Ranking (`PatternRankingTester`)

Tests all candlestick patterns and ranks them by quantitative performance metrics:

from yfinance_ta_patterns import MarketDataLoader, PatternRankingTester

data = MarketDataLoader("EURUSD", period="60d", interval="1h").get_data()

tester = PatternRankingTester(
    data,
    symbol="EURUSD",
    initial_capital=10000.0,
    position_size=1000.0,
    execution="next_open",  # Unbiased: enters on Open of bar i+1
    allow_short=True,  # Full symmetric short trades on bearish signals
    commission=1.50,  # Transaction fee per trade
    slippage=0.0001,  # Execution slippage in price units
    min_signals=5,  # Exclude patterns with < 5 signals (reduces overfitting)
    sharpe_mode="periodic",  # Accounts for 0% returns during idle hold periods
)
results = tester.test_all_patterns(min_signals=5)

top_patterns = tester.get_top_patterns(5)
for r in top_patterns:
    print(
        f"{r.pattern_name}: Win Rate={r.win_rate:.1f}%, PnL=${r.total_pnl:.2f}, "
        f"Periodic Sharpe={r.periodic_sharpe:.2f}, MaxDD=${r.max_drawdown:.2f}, "
        f"Strength={r.avg_strength:.0f}"
    )

# Export comparison report across news filters
report_df = tester.get_comparison_report()
print(report_df)

🤖 Native MCP (Model Context Protocol) Server for AI Agents

yfinance-ta-patterns includes a built-in, zero-overhead Native MCP JSON-RPC 2.0 Server (yfinance-ta-mcp) that exposes institutional technical analysis, candlestick pattern scanning, AI confluence scoring, trade setups, macroeconomic calendars, and market news directly to AI coding assistants and autonomous agent runtimes (Claude Code, Claude Desktop, Cursor, Windsurf, Google Antigravity, Gemini CLI, and any client supporting the Model Context Protocol).

Optimized for Frontier Reasoning Models (Claude 3.7 Sonnet with Extended Thinking, OpenAI o3-mini / o1, DeepSeek-R1, Gemini 2.5 Pro / Flash, and GPT-4.5).

🚀 Instant Launch

# Direct execution without prior installation (via uvx):
uvx --from yfinance-ta-patterns yfinance-ta-mcp

# Or if installed in your Python environment:
yfinance-ta-mcp

⚙️ Client Configurations

1. Claude Desktop (`claude_desktop_config.json`)

{
  "mcpServers": {
    "yfinance-ta": {
      "command": "uvx",
      "args": ["--from", "yfinance-ta-patterns", "yfinance-ta-mcp"]
    }
  }
}

2. Cursor / Windsurf (`mcp.json` or Extension Settings)

{
  "mcpServers": {
    "yfinance-ta": {
      "command": "uvx",
      "args": ["--from", "yfinance-ta-patterns", "yfinance-ta-mcp"]
    }
  }
}

🛠️ Available MCP Tools

Tool	Description	Key Arguments
`ta_scan_symbol`	Scans a symbol for active candlestick patterns, computes deterministic AI Confluence Scores (0.0–1.0), and generates ATR-based Trade Setups (Entry, Stop-Loss, TP1, TP2).	`symbol`, `timeframe`, `period`, `min_confidence`, `compact`
`ta_scan_watchlist`	High-throughput concurrent scanner across up to 25 symbols with isolated timeouts and aggregated trade opportunities.	`symbols` (list), `timeframe`, `min_confidence`
`ta_backtest_patterns`	Institutional unbiased next-open backtester ranking patterns by win rate, total PnL, periodic Sharpe, and max drawdown.	`symbol`, `period`, `timeframe`, `min_signals`, `execution`
`ta_get_economic_calendar`	Live high-impact macroeconomic calendar events relevant to the asset's currency with in-memory caching.	`symbol` (e.g. 'EURUSD', 'AAPL')
`ta_get_news`	Live market news headlines, publishers, and publication timestamps for an asset.	`symbol`, `limit`

📚 MCP Resources & Prompts

Resources:
- ta://patterns/catalog — Canonical catalog of all 61 candlestick patterns with recognition rules and runtime mode.
- ta://forex/56-pairs — Canonical universe of 56 major and cross currency pairs.
Prompts:
- ta_market_analyst_prompt — Generates structured quantitative portfolio manager reasoning prompts tailored for Claude 3.7 Sonnet, o3-mini, and DeepSeek-R1.

Development & Testing

Run the test suite and quality checks:

# Run pytest across full test suite (510+ tests)
uv run --extra dev pytest -v
# or with standard pytest
pytest -v

# Linter and formatting check
uv run --extra dev ruff check .
uv run --extra dev ruff format --check .

# Static type check
uv run --extra dev mypy yfinance_ta_patterns

# Build source distribution and binary wheel
uv build

All 602+ tests pass with 100% success rate on Linux x86_64 across CPython 3.8 through 3.15 and free-threaded CPython 3.14t (No-GIL), with cross-platform automated matrix verification on Windows and macOS.

🌐 High-Performance Systems Ecosystem

yfinance-ta-patterns is developed by @eminsk as part of an open-source engineering ecosystem:

⚡ NanoVector — Bare-metal C99/AVX2 vector search & episodic memory engine (~120KB) with Native MCP Server (pip install nanovector).
🧠 AgentJIT — Just-In-Time Compiler for AI Agent Trajectories with speculative de-optimization guards (pip install agentjit).
⚡ NanoGEMM — Minimalist, bare-metal AVX2+FMA SIMD matrix multiplication engine in ~100KB for sub-microsecond CPU neural network inference (pip install nanogemm).
🖥️ NanoRecall — 100% Private, offline desktop memory & semantic screen search engine powered by NanoVector (pip install nanorecall).
🛒 avito-sdk — Headless Avito scraping & data extraction SDK with price drop tracking, Playwright cookies, Telegram/VK bots, and Native MCP Server (pip install avito-sdk).
📊 xlsx_vievers — Headless Excel formula engine (129+ functions), desktop spreadsheet processor, SIMD SSE2 math engine, and Native MCP Server (pip install xlsx-viewer-pro).
🎥 screenvideo — Lightweight desktop screen recorder with WASAPI audio and a standalone pure x64 Flat Assembler (FASM) native edition.

☕ Support, Community & Donations

If you find this project valuable, encounter issues, or would like to support ongoing development:

⭐ Star the Repository: If yfinance-ta-patterns powers your market analysis or trading algorithms, give us a star on GitHub — it helps more traders and quants discover the tool!
🐛 Report Issues & Bugs: Found a bug, pattern calculation discrepancy, or edge case? Please open an Issue!
💬 Join Discussions: Have strategies, ideas, or custom patterns to share? Start or join a thread in GitHub Discussions!
☕ Donate (USDT TRC-20):
TDVbEdnpgNgoAhNcn1EwXxWHiR3RKLit5P
(Network: TRON / TRC-20 | Verify on TronScan)

📜 Version History & Changelog

See CHANGELOG.md for full detailed release history, technical audit notes, and benchmark comparisons.

🚀 v0.3.72 — Clarified exact verified runtime scopes in documentation: Tier-1 Linux x86_64, Windows & macOS CI matrices, wheels-only resolution for free-threaded Python 3.13t, and explicit PyPI dependency boundaries for PyPy and CPython 3.16.
🚀 v0.3.71 — Fixed MCP watchlist concurrent scan race condition on pandas 2.x shared Index._cache via _isolated_frame(), preventing spurious duplicate timestamp errors, and expanded test suite (602 tests passed).
🚀 v0.3.70 — Pinned MCP server clock in event risk tests to UTC midday, eliminating the 00:00–00:16 UTC test failure window, added 15-minute event risk grace window boundary tests, and expanded test suite (599 tests passed).
🚀 v0.3.69 — Inclusive --end-date semantics forwarding next midnight to yfinance, strict inverted range rejection (--start-date > --end-date), 1m 7-day window enforcement across single-sided ranges and inclusive calendar spans, table-driven MarketDataLoader._clamp_period_for_interval covering arbitrary periods, pure-Python fast_score_batch exact length matching without list mutation, and expanded test suite (597 tests passed).
🚀 v0.3.68 — Live Yahoo Finance 1m intraday limit separation (depth: 30d, query span: 7d), CLI span validation, gemm.py fast_score_batch oversized buffer scalar broadcasting fix across native and fallback branches, CLI --backtest error safety guarding --calendar/--news hooks, expanded ISO-3 country support (ARE, CHL, COL, MYS, PHL), module-level constant hoisting, removal of obsolete _STOCK_COLLISIONS, platform documentation for [gemm], and expanded test suite (563 tests passed).
🚀 v0.3.67 — Connected CLI --calendar and --news hooks to --backtest, added case-insensitive backtest pattern normalization and get_all_patterns() validation, multi-symbol failure isolation in JSON mode, actual date range display in ranking header, unified YAHOO_INTRADAY_MAX_DAYS with >= boundary and --start-date validation, precious metal XAU-EUR delimiter stripping (['EUR']), G10 auto-mode bare currency restrictions protecting US equities (NOK, PEN, EGP, IDR), gemm.py np.shares_memory aliasing protection, fast_score_batch out=list support, and expanded test suite (553 tests passed).
🛡️ v0.3.66 — Quantitative multi-symbol and targeted single-pattern backtesting (yftp EURUSD GBPUSD --backtest), elimination of 3x redundant runs, strict MCP schema parameter validation (clamp=False), Yahoo Finance intraday history limits and --date clamping, gemm.py out= buffer support, pure-Python linear algebra resilience ((K, 1) weights and empty batch []), macroeconomic calendar currency resolution for precious metals (XAU/XAG), and expanded test suite (539 tests passed).
🛡️ v0.3.65 — Comprehensive audit resolution: fixed CLI positional symbol deduplication (yftp SPY), unpinned nanogemm into optional extra [gemm] to prevent numpy environment conflicts, sanitized fast_score_batch float32 layout, restored cdl_hikkakemod warmup parity, corrected FX 4h Friday weekly close release timing, and excluded precious metals from macroeconomic calendar currency queries.
✨ v0.3.64 — Modernized CLI output banners with clear built-in TA-Lib status and active hardware SIMD backend reporting; removed noisy manual C-binary compilation hints from regular scans, isolating them to yftp --check-talib.
⚡ v0.3.63 — Integrated nanogemm directly into core base dependencies, enabling automatic out-of-the-box AVX2+FMA SIMD matrix acceleration for standard pip install and uv add commands without requiring manual extra flags.
🚀 v0.3.62 — Integrated hybrid linear algebra & NanoGEMM AVX2+FMA SIMD matrix acceleration engine (yfinance_ta_patterns.gemm), fast_matmul, fast_score_batch, cosine_similarity_matrix, CLI diagnostic ISA display (yftp --check-talib), dynamic PyPI and Conda download badges, and expanded test suite (512 tests passed).
🛡️ v0.3.61 — Deep audit resolution across Forex Friday close retention over weekends, Yahoo Finance intraday history clamping (730d), CLI --format json purity, precious metals normalization (XAU/XAG), macroeconomic calendar equity ticker shielding, TA-Lib warmup parity, and MCP JSON-RPC 2.0 batch support.
🤖 v0.3.60 — Positional symbol CLI arguments (yftp SPY NVDA), native --mcp flag, and Smithery AI Agent Registry integration.
📦 v0.3.59 — Zero-binary autonomous packaging without mandatory external C TA-Lib or scikit-learn.
🧪 v0.3.45 — 100.000% mathematical parity with canonical C TA-Lib across all 61 candlestick patterns.

License

MIT License. See LICENSE for details.

Name		Name	Last commit message	Last commit date
.github		.github
aur		aur
conda-recipe		conda-recipe
debian		debian
devto		devto
examples		examples
notebooks		notebooks
recipe		recipe
scripts		scripts
tests		tests
yfinance_ta_patterns		yfinance_ta_patterns
.gitignore		.gitignore
.python-version		.python-version
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
conftest.py		conftest.py
main.py		main.py
pyproject.toml		pyproject.toml
smithery.yaml		smithery.yaml
uv.lock		uv.lock

Latest commit

History

Folders and files

Repository files navigation

Market Candlestick & AI Pattern Scanner (yfinance-ta-patterns)

🤝 Community, Issues & Support

Key Features

🧩 Compatibility & Runtime Verification Matrix

Quick start

1. Installation

🚀 Quick Installation by Platform

Option A: Using uv (Fastest & Recommended)

⚡ Free-Threaded Python / No-GIL Guide (PEP 703: 3.14t verified, 3.13t wheels-only)

1. Python Version Selection & Wheel Availability

2. Understanding Automatic GIL Re-Enablement

3. Running in True No-GIL Mode

4. Verification

Option B: Using Standard pip

Option C: Native C TA-Lib on Linux & macOS (Optional)

🐍 Python Version Compatibility Matrix

🤖 Native MCP (Model Context Protocol) Server

Option 1: Claude Code CLI

Option 2: Antigravity / Claude Desktop / Cursor / Windsurf (mcp_config.json)

🚀 Ready-to-Use Examples (examples/)

1. Multi-Pair Historical Backtesting (examples/multi_pair_backtest.py)

2. Live Multi-Asset Signal Scanner (examples/live_signals_scanner.py)

2. Run CLI

CLI Reference

Options

Python API

1. Universal Multi-Asset Data Loader (MarketDataLoader)

2. AI Pattern Confidence Scorer (AIPatternScorer)

3. AI Market Analyst & LLM Prompting (AIMarketAnalyst)

4. Quantitative Backtesting & Pattern Ranking (PatternRankingTester)

🤖 Native MCP (Model Context Protocol) Server for AI Agents

🚀 Instant Launch

⚙️ Client Configurations

1. Claude Desktop (claude_desktop_config.json)

2. Cursor / Windsurf (mcp.json or Extension Settings)

🛠️ Available MCP Tools

📚 MCP Resources & Prompts

Development & Testing

🌐 High-Performance Systems Ecosystem

☕ Support, Community & Donations

📜 Version History & Changelog

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages