Metadata-Version: 2.4
Name: vectrade-finkit
Version: 0.1.0
Summary: Open-source financial indicators, signals, and risk models
Project-URL: Homepage, https://github.com/VecTrade-io/finkit
Project-URL: Documentation, https://docs.vectrade.io/sdks/finkit
Project-URL: Repository, https://github.com/VecTrade-io/finkit
Project-URL: Changelog, https://github.com/VecTrade-io/finkit/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/VecTrade-io/finkit/issues
Author-email: VecTrade <oss@vectrade.io>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: backtesting,finance,indicators,quant,risk,signals,trading
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Provides-Extra: dev
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# finkit

[![CI](https://github.com/VecTrade-io/finkit/actions/workflows/ci.yml/badge.svg)](https://github.com/VecTrade-io/finkit/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/vectrade-finkit)](https://pypi.org/project/vectrade-finkit/)
[![License](https://img.shields.io/github/license/VecTrade-io/finkit)](LICENSE)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![Coverage](https://img.shields.io/badge/coverage-99%25-brightgreen)](https://github.com/VecTrade-io/finkit)

Open-source financial analysis library. Production-grade indicators, signals, risk metrics, screening, and cost analysis.

**No VecTrade account required** — this is a standalone library for the quant/fintech community.

## Installation

```bash
pip install vectrade-finkit
```

## Quick Start

```python
import pandas as pd
import finkit

# ── Technical Indicators ──
df["sma_20"] = finkit.sma(df["close"], period=20)
df["ema_12"] = finkit.ema(df["close"], period=12)
df["rsi"] = finkit.rsi(df["close"], period=14)
macd_line, signal, histogram = finkit.macd(df["close"])
upper, middle, lower = finkit.bollinger_bands(df["close"])
df["atr"] = finkit.atr(df["high"], df["low"], df["close"], period=14)
df["vwap"] = finkit.vwap(df["high"], df["low"], df["close"], df["volume"])
df["obv"] = finkit.obv(df["close"], df["volume"])

# ── Signal Detection ──
df["buy_signal"] = finkit.crossover(df["sma_10"], df["sma_50"])
df["sell_signal"] = finkit.crossunder(df["sma_10"], df["sma_50"])
df["divergence"] = finkit.divergence(df["close"], df["rsi"])

# ── Signal Engine (composable rules) ──
engine = finkit.SignalEngine()
engine.add_rule("rsi_oversold", lambda df: df["rsi"] < 30, direction="long")
engine.add_rule("macd_cross", lambda df: finkit.crossover(df["macd"], df["signal"]), direction="long")
signals = engine.evaluate(df)

# ── Risk Metrics ──
sharpe = finkit.sharpe_ratio(returns, risk_free_rate=0.04)
sortino = finkit.sortino_ratio(returns)
mdd = finkit.max_drawdown(equity_curve)
value_at_risk = finkit.var(returns, confidence=0.95)

# ── Stock Screening ──
from finkit import Rule, screen

results = screen(universe_df, rules=[
    Rule("pe_ratio", "<", 25),
    Rule("market_cap", ">", 10_000_000_000),
    Rule("rsi_14", "between", (30, 70)),
    Rule("sector", "in", ["Technology", "Healthcare"]),
])

# ── Cost Analysis ──
cost = finkit.calculate_trade_cost(shares=100, price=150.0, commission_per_share=0.005)
drag = finkit.annual_cost_drag(trades_per_year=200, avg_trade_cost=cost.total, portfolio_value=100_000)
```

## API Reference

### `finkit.indicators`

| Function | Signature | Description |
|----------|-----------|-------------|
| `sma` | `(series, period=20)` | Simple Moving Average |
| `ema` | `(series, period=20)` | Exponential Moving Average |
| `rsi` | `(series, period=14)` | Relative Strength Index (0–100) |
| `macd` | `(series, fast=12, slow=26, signal=9)` | MACD → `(line, signal, histogram)` |
| `bollinger_bands` | `(series, period=20, std_dev=2.0)` | Bollinger → `(upper, middle, lower)` |
| `atr` | `(high, low, close, period=14)` | Average True Range (volatility) |
| `vwap` | `(high, low, close, volume)` | Volume Weighted Average Price |
| `obv` | `(close, volume)` | On-Balance Volume |

### `finkit.signals`

| Function | Signature | Description |
|----------|-----------|-------------|
| `crossover` | `(fast, slow)` | Bullish crossover detection (boolean Series) |
| `crossunder` | `(fast, slow)` | Bearish crossunder detection (boolean Series) |
| `divergence` | `(price, indicator, window=14)` | Bullish divergence detection |
| `SignalEngine` | class | Composable rule-based signal scoring engine |

### `finkit.risk`

| Function | Signature | Description |
|----------|-----------|-------------|
| `sharpe_ratio` | `(returns, risk_free_rate=0.0, periods=252)` | Annualized Sharpe Ratio |
| `sortino_ratio` | `(returns, risk_free_rate=0.0, periods=252)` | Sortino Ratio (downside only) |
| `max_drawdown` | `(returns)` | Maximum peak-to-trough drawdown |
| `var` | `(returns, confidence=0.95, method="historical")` | Value at Risk (historical or parametric) |

### `finkit.screen`

| Function | Signature | Description |
|----------|-----------|-------------|
| `Rule` | `(field, operator, value)` | Screening rule definition |
| `screen` | `(df, rules)` | Apply rules and return matching rows |

**Supported operators:** `<`, `<=`, `>`, `>=`, `==`, `!=`, `between`, `in`, `contains`

### `finkit.costs`

| Function | Signature | Description |
|----------|-----------|-------------|
| `calculate_trade_cost` | `(shares, price, *, commission_per_share, ...)` | Total trade cost breakdown |
| `annual_cost_drag` | `(trades_per_year, avg_trade_cost, portfolio_value)` | Annualized cost as portfolio drag |
| `TradeCost` | dataclass | Structured cost result |

## Design Principles

- **Zero API dependency** — works with any pandas DataFrame
- **NumPy vectorized** — fast computation on large datasets
- **Minimal dependencies** — only `numpy` and `pandas`
- **Fully typed** — `py.typed` marker, works with mypy/pyright
- **Well-tested** — 99% branch coverage

## Part of the VecTrade Ecosystem

| Package | Description |
|---------|-------------|
| [`vectrade`](https://github.com/VecTrade-io/vectrade-python) | Python SDK for VecTrade API |
| [`@vectrade/sdk`](https://github.com/VecTrade-io/vectrade-node) | TypeScript/Node SDK |
| [`vectrade-finkit`](https://github.com/VecTrade-io/finkit) | Financial computation library (this package) |
| [`@vectrade/ai-provider`](https://github.com/VecTrade-io/vectrade-ai-provider) | Vercel AI SDK provider |

## Documentation

Full documentation is available at [docs.vectrade.io/sdks/finkit](https://docs.vectrade.io/sdks/finkit).

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.

## License

Apache-2.0 — see [LICENSE](LICENSE).
