Metadata-Version: 2.4
Name: smart-money-heatmap
Version: 0.2.0
Summary: Smart Money Concepts signal heatmap for NSE instruments via Nubra SDK.
License: MIT License
        
        Copyright (c) 2026 Nubra
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Source Code, https://github.com/nubra/smart-money-heatmap
Project-URL: Bug Tracker, https://github.com/nubra/smart-money-heatmap/issues
Keywords: trading,smart money,nse,heatmap,order block,bos,choch,vwap,oi wall
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT 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
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=1.5
Dynamic: license-file

# smart-money-heatmap

Score NSE instruments against eight Smart Money Concepts signals and get a single aggregate conviction score — bullish, bearish, or neutral.

Built on top of the [Nubra Python SDK](https://nubra.in) for live NSE market data.

---

## Project Description

`smart-money-heatmap` analyses every instrument you give it across eight institutional-behaviour signals:

| Signal | What it detects |
|--------|----------------|
| **VWAP Deviation** | How far price has moved from the intraday volume-weighted average |
| **OI Wall Proximity** | Nearest significant options open-interest support / resistance wall |
| **Break of Structure (BOS)** | Price closing beyond a confirmed swing high or swing low |
| **Change of Character (CHoCH)** | A structural reversal — break against the prior trend |
| **Imbalance / Displacement** | A high-volume, wide-body candle signalling institutional entry |
| **Fair Value Gap (FVG)** | An unfilled price gap between candle 1 and candle 3 |
| **Order Block** | Net score across all active unmitigated order block zones |
| **Liquidity** | Current volume vs session baseline, used as a confidence multiplier |

Each signal scores from **−100** (bearish) to **+100** (bullish). The aggregate score is a weighted average of all signals, penalised for inter-signal conflict and scaled by session liquidity.

---

## Install

```bash
pip install smart-money-heatmap
```

Requires Python ≥ 3.9 and an authenticated [Nubra](https://nubra.in) account for live data.

---

## Usage

### Python

```python
from nubra_python_sdk.start_sdk import InitNubraSdk, NubraEnv
from smart_money_heatmap import SmartMoneyHeatmap

nubra  = InitNubraSdk(NubraEnv.PROD, env_creds=True)
hm     = SmartMoneyHeatmap(sdk=nubra)

result = hm.compute(
    instruments=["HDFCBANK", "RELIANCE", "SBIN", "NIFTY"],
    timeframe="5m",            # 1m | 5m | 15m | 1h | 1d
    include_option_chain=True, # set False to skip OI Wall (faster)
)
```

### CLI

```bash
smheatmap --symbols HDFCBANK RELIANCE SBIN NIFTY --timeframe 5m
```

---

## Output Format


### Score interpretation

| Score | Verdict |
|-------|---------|
| > +60 | 🟢 Strongly Bullish |
| +25 to +60 | 🟢 Bullish |
| +15 to +25 | 🟡 Mildly Bullish |
| −15 to +15 | ⚪ Neutral |
| −25 to −15 | 🟠 Mildly Bearish |
| −60 to −25 | 🔴 Bearish |
| < −60 | 🔴 Strongly Bearish |

▲ signal is bullish &nbsp;·&nbsp; ▼ signal is bearish &nbsp;·&nbsp; — neutral or no edge

---

## Raw Data

Behind the printed output, everything is plain Python dicts and DataFrames.

### `result.data` — scores only

```python
result.data
# {
#   "HDFCBANK": {"liquidity": 19.3, "vwap": 0.0, "oi_wall": 0.0, "bos": 0.0,
#                "choch": 0.0, "imbalance": 0.0, "fvg": 9.4, "order_block": 0.0,
#                "aggregate": 0.7},
#   "RELIANCE": {"liquidity": 27.6, "vwap": 56.4, "oi_wall": 0.0, "bos": 28.3,
#                "choch": 0.0, "imbalance": 40.0, "fvg": 58.0, "order_block": 64.5,
#                "aggregate": 25.8},
#   ...
# }
```

### `result.explain("RELIANCE")` — full breakdown per instrument

```python
result.explain("RELIANCE")
# {
#   "symbol": "RELIANCE",
#   "current_price": 1452.30,
#   "timeframe": "5m",
#   "data_quality": {"ok": True, "status": "valid", "reason": "..."},
#   "summary": "RELIANCE is bullish with medium confidence. Aggregate score: +25.8.",
#
#   "signals": {
#     "vwap": {
#       "name":        "vwap",
#       "score":       56.4,
#       "status":      "valid",
#       "direction":   "bullish",
#       "confidence":  0.564,
#       "directional": True,
#       "reason":      "Price is 0.52% above VWAP, showing bullish intraday positioning.",
#       "debug": {
#         "close": 1452.30, "vwap": 1444.80,
#         "distance_percent": 0.52, "session_rows": 35
#       }
#     },
#     "order_block": {
#       "name":        "order_block",
#       "score":       64.5,
#       "status":      "valid",
#       "direction":   "bullish",
#       "confidence":  0.645,
#       "directional": True,
#       "reason":      "Net OB score +64.5 from 3 active zone(s) (2 bullish, 1 bearish).",
#       "debug": {
#         "net_score": 64.5,
#         "current_price": 1452.30,
#         "active_ob_zones": [
#           {"type": "bullish", "low": 1440.0, "high": 1445.0,
#            "score": 72.1, "distance_percent": 0.5, "mitigated": False, ...},
#           ...
#         ],
#         "detected_bullish_ob_zones": [...],
#         "detected_bearish_ob_zones": [...]
#       }
#     },
#     # ... same structure for: liquidity, oi_wall, bos, choch, imbalance, fvg
#   },
#
#   "aggregate": {
#     "score":       25.8,
#     "bias":        "bullish",
#     "confidence":  "medium",
#     "explanation": "Aggregate score is +25.8, bias is bullish, confidence is medium.",
#     "bullish_reasons": ["vwap: Price is 0.52% above VWAP...", "bos: Bullish BOS...", ...],
#     "bearish_reasons": [],
#     "neutral_or_missing_reasons": ["choch: No CHoCH detected.", ...],
#     "debug": {
#       "raw_score": 29.1, "adjusted_score": 25.8,
#       "conflict_ratio": 0.0, "liquidity_confidence": 1.08,
#       "availability_ratio": 0.9, "bullish_pressure": 18.4, "bearish_pressure": 0.0
#     }
#   }
# }
```

### `result.to_dataframe()` — signals × instruments

```python
result.to_dataframe()
#              HDFCBANK  RELIANCE   SBIN  NIFTY
# liquidity        19.3      27.6   24.2   23.0
# vwap              0.0      56.4   29.0   26.3
# oi_wall           0.0       0.0    0.0    0.0
# bos               0.0      28.3    0.0   32.1
# choch             0.0       0.0    0.0    0.0
# imbalance         0.0      40.0  -32.5    0.0
# fvg               9.4      58.0   35.9   -8.7
# order_block       0.0      64.5    6.4   20.1
# aggregate         0.7      25.8    1.6    5.7
```

---

## Result API

```python
result.to_dataframe()        # pd.DataFrame  —  signals × instruments
result.status_dataframe()    # signal statuses per instrument
result.reasons_dataframe()   # one-line reason per signal per instrument
result.top_n(3)              # top 3 instruments by aggregate score
result.explain("RELIANCE")   # full breakdown dict for one instrument
result.to_html()             # HTML table for notebooks / dashboards
```

---

## Configuration

Override signal defaults via the `config` parameter:

```python
result = hm.compute(
    instruments=["NIFTY"],
    timeframe="5m",
    config={
        "signals": {
            "bos":         {"min_break_percent": 0.02},
            "choch":       {"min_break_percent": 0.02},
            "order_block": {"displacement_volume_ratio": 1.5},
        }
    },
)
```

---

## License

MIT
