ml4t-india

Algorithmic trading for Indian markets (NSE, BSE) on top of the ML4T library ecosystem.

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 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:

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 — 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

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 — login, historical data, backtesting, option chain, live trading, NSE calendar
• Integration Testing — real broker smoke tests with OS keychain credential storage (no secrets in git)
• Releasing — tag-triggered PyPI publish via OIDC + conda-forge recipe workflow

Full documentation will be published to 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.

# 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 for VPS/Linux setup, troubleshooting, and security properties.

License

Not licensed yet.