Metadata-Version: 2.4
Name: ml4t-india
Version: 0.1.0
Summary: Algorithmic trading for Indian markets (NSE, BSE) on top of the ml4t-* ecosystem
Project-URL: Repository, https://github.com/shankarpandala/ml4t-india
Project-URL: Issues, https://github.com/shankarpandala/ml4t-india/issues
Author: Shankar Pandala
Keywords: backtesting,bse,finance,india,kite,live-trading,ml4t,nse,quantitative-finance,trading,zerodha
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: click>=8
Requires-Dist: httpx<1,>=0.27
Requires-Dist: kiteconnect>=5.0.0
Requires-Dist: ml4t-backtest
Requires-Dist: ml4t-data
Requires-Dist: ml4t-diagnostic
Requires-Dist: ml4t-engineer
Requires-Dist: ml4t-live
Requires-Dist: pandas-market-calendars>=4.3.0
Requires-Dist: pandas>=2
Requires-Dist: polars>=0.20
Requires-Dist: pyarrow>=14
Requires-Dist: pydantic-settings>=2
Requires-Dist: pydantic>=2
Requires-Dist: pytz>=2024.1
Requires-Dist: pyyaml>=6
Requires-Dist: rich>=13
Requires-Dist: structlog>=23
Requires-Dist: tenacity>=8
Provides-Extra: all
Requires-Dist: hypothesis>=6.80; extra == 'all'
Requires-Dist: keyring>=25; extra == 'all'
Requires-Dist: mkdocs-jupyter>=0.24; extra == 'all'
Requires-Dist: mkdocs-material>=9.5; extra == 'all'
Requires-Dist: mkdocs<2,>=1.6; extra == 'all'
Requires-Dist: mkdocstrings[python]>=0.24; extra == 'all'
Requires-Dist: ml4t-diagnostic[viz]; extra == 'all'
Requires-Dist: plotly>=5; extra == 'all'
Requires-Dist: pre-commit>=3; extra == 'all'
Requires-Dist: py-vollib>=1.0.1; extra == 'all'
Requires-Dist: pytest-asyncio>=0.23; extra == 'all'
Requires-Dist: pytest-cov>=4.1; extra == 'all'
Requires-Dist: pytest-timeout>=2.1; extra == 'all'
Requires-Dist: pytest>=8; extra == 'all'
Requires-Dist: respx>=0.21; extra == 'all'
Requires-Dist: ruff>=0.8; extra == 'all'
Requires-Dist: ty; extra == 'all'
Requires-Dist: vcrpy>=6; extra == 'all'
Provides-Extra: dev
Requires-Dist: hypothesis>=6.80; extra == 'dev'
Requires-Dist: keyring>=25; extra == 'dev'
Requires-Dist: pre-commit>=3; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=4.1; extra == 'dev'
Requires-Dist: pytest-timeout>=2.1; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Requires-Dist: ty; extra == 'dev'
Requires-Dist: vcrpy>=6; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-jupyter>=0.24; extra == 'docs'
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocs<2,>=1.6; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
Provides-Extra: options
Requires-Dist: py-vollib>=1.0.1; extra == 'options'
Provides-Extra: viz
Requires-Dist: ml4t-diagnostic[viz]; extra == 'viz'
Requires-Dist: plotly>=5; extra == 'viz'
Description-Content-Type: text/markdown

# ml4t-india

[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![Free-threaded: experimental](https://img.shields.io/badge/free--threaded-experimental-orange.svg)](docs/free-threaded.md)

Algorithmic trading for Indian markets (NSE, BSE) on top of the
[ML4T library ecosystem](https://ml4trading.io/libraries/).

> **Status:** pre-alpha. Phase-1 Zerodha Kite integration complete. Publishing pipeline ready.

## What this is

`ml4t-india` is a thin extension layer that adapts the five ML4T companion
libraries to Indian equity and derivatives markets via the
[Zerodha Kite Connect v3](https://kite.trade/docs/connect/v3/) broker API.

It contributes **only what is India-specific**. Every generic capability
(engine, indicators, diagnostics, risk framework, storage) is delegated to
the upstream libraries unchanged:

| Upstream library | Role | India-specific work |
| ---------------- | ---- | ------------------- |
| [`ml4t-data`](https://github.com/shankarpandala/data) | `DataManager`, `BaseProvider`, storage | `KiteProvider`, bhavcopy providers |
| [`ml4t-engineer`](https://github.com/shankarpandala/engineer) | 120 indicators, labeling, alt bars | None &mdash; consumed as-is |
| [`ml4t-backtest`](https://github.com/shankarpandala/backtest) | Event-driven engine, `Strategy`, presets | `IndianChargesModel`, `nse_india` preset |
| [`ml4t-live`](https://github.com/shankarpandala/live) | `LiveEngine`, `SafeBroker`, protocols | `KiteBroker`, `KiteTickerFeed` |
| [`ml4t-diagnostic`](https://github.com/shankarpandala/diagnostic) | DSR, CPCV, tear sheets | Calendar wiring only |

## Design principles

- **Extend, don't re-implement.** Every adapter subclasses the upstream
  concrete base where one exists (e.g. `IndianOHLCVProvider(BaseProvider)`).
  Where upstream only exposes a `typing.Protocol`, we implement it once in
  an India-level abstract base (`IndianBrokerBase`, `IndianTickerFeedBase`)
  and every concrete broker extends that &mdash; so the protocol is adhered
  to exactly once.
- **Drift-insulated.** The weekly `upstream-drift` CI job installs the
  latest `ml4t-*` from PyPI and re-runs the full suite. Signature-level
  drift is caught by dedicated snapshot tests.
- **Pure Python.** No C extensions of our own, so a single universal wheel
  serves both GIL and free-threaded CPython. See `docs/free-threaded.md`.
- **TDD at every adapter boundary.** Contract tests verify substitutability
  for upstream protocols; recorded HTTP cassettes drive integration.

## Phase-1 scope (Zerodha, full surface)

- Historical candles (1m, 3m, 5m, 10m, 15m, 30m, 60m, day), OI, continuous F&O.
- `KiteTicker` WebSocket (ltp / quote / full modes, 3000 instruments / connection, 3 connections).
- Orders: regular / AMO / CO / iceberg / auction.
- Product types: CNC / MIS / NRML / MTF.
- Option chain with Greeks (Black-Scholes) and analytics (PCR, max-pain, ATM ladder).
- Zerodha fee schedule: brokerage + STT + exchange turnover + GST + SEBI + stamp.
- Bhavcopy bulk providers: NSE / BSE / MCX for long-history backfill.

## Installation

```bash
pip install ml4t-india           # core
pip install ml4t-india[options]  # + Black-Scholes Greeks
pip install ml4t-india[viz]      # + plotly tear sheets
pip install ml4t-india[all]
```

## Documentation

- [Quickstart](docs/quickstart.md) — login, historical data, backtesting,
  option chain, live trading, NSE calendar
- [Integration Testing](docs/integration-testing.md) — real broker smoke
  tests with OS keychain credential storage (no secrets in git)
- [Releasing](docs/releasing.md) — tag-triggered PyPI publish via OIDC +
  conda-forge recipe workflow

Full documentation will be published to
[https://shankarpandala.github.io/ml4t-india/](https://shankarpandala.github.io/ml4t-india/)
once Phase-1 stabilises.

## Integration Testing

Real broker tests run locally against a live Zerodha Kite account. Credentials
are stored in the OS keychain — never in `.env` files, config files, or git.

```bash
# Store credentials once (Windows Credential Manager / GNOME Keyring / macOS Keychain)
python scripts/store_kite_credentials.py

# Daily refresh (Kite tokens expire at ~06:00 IST)
python scripts/store_kite_credentials.py --refresh

# Run the 6-test smoke suite
pytest tests/integration -m integration -v
```

Tests skip cleanly when credentials are absent. They never run on GitHub
Actions. See [docs/integration-testing.md](docs/integration-testing.md) for
VPS/Linux setup, troubleshooting, and security properties.

## License

Not licensed yet.
