Metadata-Version: 2.4
Name: motosan-ta-sdk
Version: 0.4.0
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

Core Python SDK for technical analysis — OHLCV data fetching, indicators, pattern detection, screening, and risk assessment.

## Installation

```bash
pip install motosan-ta-sdk

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

Or with `uv` from the monorepo root:

```bash
uv sync
```

## Quick Start

```python
from ta_sdk import YFinanceProvider, sma, ema, check_stage2, detect_vcp

provider = YFinanceProvider()

# Fetch OHLCV data
ohlcv = provider.get_ohlcv("AAPL", period="1y", interval="1d")

# Calculate indicators
sma_50 = sma(ohlcv.df["close"], 50)
ema_21 = ema(ohlcv.df["close"], 21)

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

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

## Top-Level Exports

All main APIs are available directly from `ta_sdk`:

```python
from ta_sdk import (
    # Data
    OHLCVData, Quote, PatternResult, AnalysisReport,
    YFinanceProvider, BinanceProvider, MultiProvider,
    # Indicators
    sma, ema, rsi, macd, atr, bollinger_bands, obv,
    # Screeners
    check_stage2, check_entry_signal,
    # Patterns
    detect_vcp, detect_cup_handle, detect_double_bottom,
    # Analysis
    analyze_stock,
)
```

## Module Overview

| Module | Description | Key Exports |
|--------|-------------|-------------|
| `data` | Data providers, models, caching | `YFinanceProvider`, `BinanceProvider`, `MultiProvider`, `CachedProvider` |
| `indicators` | Technical indicators | `sma`, `ema`, `rsi`, `macd`, `atr`, `bollinger_bands`, `obv` |
| `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)
