Metadata-Version: 2.4
Name: motosan-ta-sdk
Version: 0.4.1
Summary: Core Python SDK for technical analysis — OHLCV data, indicators, pattern detection, screening, and risk assessment.
Project-URL: Homepage, https://github.com/daiwanwei/motosan-ta
Project-URL: Repository, https://github.com/daiwanwei/motosan-ta
License-Expression: MIT
Keywords: crypto,indicators,stage2,stocks,technical-analysis,trading,vcp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.12
Requires-Dist: numpy>=1.26
Requires-Dist: pandas>=2.2
Requires-Dist: python-binance>=1.0.19
Requires-Dist: requests>=2.31
Requires-Dist: yfinance>=0.2.36
Provides-Extra: cache
Requires-Dist: diskcache>=5.6; extra == 'cache'
Provides-Extra: dev
Requires-Dist: diskcache>=5.6; extra == 'dev'
Requires-Dist: pytest-cov>=4.1; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: parity
Requires-Dist: pandas-ta>=0.3; extra == 'parity'
Description-Content-Type: text/markdown

# motosan-ta-sdk

[![CI](https://github.com/daiwanwei/motosan-ta/actions/workflows/ci-python.yml/badge.svg)](https://github.com/daiwanwei/motosan-ta/actions/workflows/ci-python.yml)
[![PyPI](https://img.shields.io/pypi/v/motosan-ta-sdk)](https://pypi.org/project/motosan-ta-sdk/)
[![Python](https://img.shields.io/pypi/pyversions/motosan-ta-sdk)](https://pypi.org/project/motosan-ta-sdk/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/daiwanwei/motosan-ta/blob/main/LICENSE)

Core Python SDK for technical analysis — 20 indicators, pattern detection, screening, and risk assessment. Strict parity with [pandas-ta](https://github.com/twopirllc/pandas-ta) reference vectors.

- **GitHub:** [daiwanwei/motosan-ta](https://github.com/daiwanwei/motosan-ta)
- **Changelog:** [CHANGELOG.md](https://github.com/daiwanwei/motosan-ta/blob/main/CHANGELOG.md)
- **Rust crates:** [motosan-ta-math](https://crates.io/crates/motosan-ta-math), [motosan-ta-stream](https://crates.io/crates/motosan-ta-stream)

## Installation

```bash
pip install motosan-ta-sdk

# With disk caching support
pip install motosan-ta-sdk[cache]
```

## Quick Start

```python
from ta_sdk import YFinanceProvider, sma, ema, rsi, macd, atr, check_stage2, detect_vcp

provider = YFinanceProvider()
ohlcv = provider.get_ohlcv("AAPL", period="1y", interval="1d")
df = ohlcv.df

# Indicators
sma_50 = sma(df["close"], 50)
ema_21 = ema(df["close"], 21)
rsi_14 = rsi(df["close"], 14)
macd_line, signal, hist = macd(df["close"])
atr_14 = atr(df["high"], df["low"], df["close"], 14)

# Screen for Stage 2 trend
result = check_stage2(df)
print(f"Stage 2: {result['passes']} ({result['score']}/{result['max_score']})")

# Detect VCP pattern
vcp = detect_vcp(df)
print(f"VCP: {vcp.detected} (confidence: {vcp.confidence:.0%})")
```

## Indicators (20 total)

**Moving Averages (7):** SMA, EMA, KAMA, DEMA, TEMA, HMA, SMMA
**Momentum (10):** RSI, MACD, Stochastic, CCI, Williams %R, MFI, ROC, Aroon, TSI, Fisher Transform, TRIX
**Volatility (6):** ATR, Bollinger Bands, ADX, Keltner Channels, Donchian Channels, Supertrend
**Volume (2):** OBV, CMF

All indicators use SMA-seeded EMA / Wilder's RMA to match pandas-ta output.

## Top-Level Exports

```python
from ta_sdk import (
    # Data
    OHLCVData, Quote, PatternResult, AnalysisReport,
    YFinanceProvider, BinanceProvider, MultiProvider,
    # Indicators — Moving Averages
    sma, ema, kama, dema, tema, hma, smma,
    # Indicators — Momentum
    rsi, macd, aroon, tsi, fisher_transform, trix,
    # Indicators — Volatility
    atr, bollinger_bands,
    # Indicators — Volume
    obv, cmf,
    # Screeners
    check_stage2, check_entry_signal,
    # Patterns
    detect_vcp, detect_cup_handle, detect_double_bottom,
    # Analysis
    analyze_stock,
)
```

Additional indicators available via direct module import:

```python
from ta_sdk.indicators.momentum import stochastic, cci, roc, williams_r, mfi
from ta_sdk.indicators.volatility import adx, keltner, donchian, supertrend
```

## Module Overview

| Module | Description | Key Exports |
|--------|-------------|-------------|
| `data` | Data providers, models, caching | `YFinanceProvider`, `BinanceProvider`, `MultiProvider`, `CachedProvider` |
| `indicators.moving_averages` | Moving averages | `sma`, `ema`, `kama`, `dema`, `tema`, `hma`, `smma` |
| `indicators.momentum` | Momentum oscillators | `rsi`, `macd`, `stochastic`, `cci`, `roc`, `williams_r`, `mfi`, `aroon`, `tsi`, `fisher_transform`, `trix` |
| `indicators.volatility` | Volatility & trend | `atr`, `bollinger_bands`, `adx`, `keltner`, `donchian`, `supertrend` |
| `indicators.volume` | Volume indicators | `obv`, `cmf` |
| `screeners` | Stock screening criteria | `check_stage2`, `check_entry_signal` |
| `patterns` | Chart pattern detection | `detect_vcp`, `detect_cup_handle`, `detect_double_bottom` |
| `analysis` | Full analysis & reports | `analyze_stock` |
| `risk` | Risk management | `calc_position_size`, `calc_rr_ratio` |

## Data Providers

| Provider | Class | Markets | API Key |
|----------|-------|---------|---------|
| Yahoo Finance | `YFinanceProvider` | US, TW | Not required |
| Binance | `BinanceProvider` | Crypto | Not required |
| FMP | `FMPProvider` | US (fundamentals) | Required |
| Multi | `MultiProvider` | Auto-routed | -- |
| Cached | `CachedProvider` | Wraps any provider | -- |

### MultiProvider

Routes symbols to the correct provider automatically based on symbol format:

```python
from ta_sdk import YFinanceProvider, BinanceProvider, MultiProvider
from ta_sdk.data.models import Market

multi = MultiProvider()
multi.register(Market.US, YFinanceProvider())
multi.register(Market.TW, YFinanceProvider())
multi.register(Market.CRYPTO, BinanceProvider())

multi.get_ohlcv("AAPL")      # Auto-detected as US
multi.get_ohlcv("2330.TW")   # Auto-detected as TW
multi.get_ohlcv("BTCUSDT")   # Auto-detected as Crypto
```

### CachedProvider

Wraps any `DataProvider` with disk-based caching. Requires the `[cache]` extra.

```python
from ta_sdk.data.cached_provider import CachedProvider

cached = CachedProvider(
    provider=YFinanceProvider(),
    cache_dir=".ta_cache",
    ohlcv_ttl=3600,   # 1 hour
    quote_ttl=60,      # 1 minute
)
ohlcv = cached.get_ohlcv("AAPL")
```

## Supported Markets

| Market | Example Symbol | Provider | Currency | Timezone |
|--------|---------------|----------|----------|----------|
| US Stocks | `AAPL` | YFinance | USD | America/New_York |
| TW Stocks | `2330.TW` | YFinance | TWD | Asia/Taipei |
| Crypto | `BTCUSDT` | Binance | USDT | UTC |

## Requirements

- Python >= 3.12
- pandas >= 2.2
- numpy >= 1.26
- yfinance >= 0.2.36
- python-binance >= 1.0.19
- requests >= 2.31
- diskcache >= 5.6 (optional, for `[cache]` extra)

## License

[MIT](https://github.com/daiwanwei/motosan-ta/blob/main/LICENSE)
