README.md

---
language: en
license: mit
tags:
  - finance
  - trading
  - time-series
  - recurrent-neural-network
  - market-regime
  - pytorch
  - interpretable-ai
library_name: strata-market
pipeline_tag: time-series-forecasting
---

# StrataNet — Market Trading Neural Architecture

**StrataNet** is a novel recurrent neural network architecture purpose-built for
market trading. It is a direct competitor to LSTM/GRU/Transformer for financial
time-series, but with a fully **interpretable hidden state** and outputs designed
specifically for trading decision support.

> **Install:** `pip install strata-market`  
> **GitHub:** https://github.com/rafaelsistems/strata-market  
> **PyPI:** https://pypi.org/project/strata-market/

---

## What makes StrataNet different?

| | LSTM / GRU | Transformer | **StrataNet** |
|---|---|---|---|
| Domain | General | General | **Market trading only** |
| Hidden state | Opaque N-dim vector | Attention weights | **4-dim, fully interpretable** |
| State bounds | None | None | **Hard bounds per dimension** |
| Output | Price / probability | Token / probability | **LONG/SHORT/HOLD + regime** |
| Label source | Future price required | Manual labels | **Auto from STRATA teacher** |
| Parameters | Millions | Millions | **~5,000 (default)** |

### Interpretable Hidden State

Unlike LSTM/GRU where the hidden state is an opaque vector, StrataNet's hidden
state directly encodes market concepts — at every timestep, always:

```
h = [bias, momentum, trap_risk, uncertainty]

bias        ∈ [-1, 1]   directional conviction (negative=bearish, positive=bullish)
momentum    ∈ [ 0, 1]   structural energy from breakouts and volume
trap_risk   ∈ [ 0, 1]   adverse selection / liquidity trap pressure
uncertainty ∈ [ 0, 1]   volatility-driven ambiguity
```

---

## Pretrained Models

This repository contains pretrained weights trained on synthetic OHLCV data
with realistic volatility profiles matching each asset class.

| File | Asset | Profile | Params |
|---|---|---|---|
| `aapl_net.pt` | AAPL | Medium volatility (large-cap tech) | ~5,000 |
| `tsla_net.pt` | TSLA | High volatility (growth/momentum) | ~5,000 |
| `spy_net.pt`  | SPY  | Low volatility (broad market ETF) | ~5,000 |
| `nvda_net.pt` | NVDA | High volatility (semiconductor) | ~5,000 |
| `qqq_net.pt`  | QQQ  | Medium volatility (tech ETF) | ~5,000 |
| `btc_net.pt`  | BTC  | High volatility (crypto) | ~5,000 |

---

## Quick Start

### Load pretrained model

```python
from huggingface_hub import hf_hub_download
from strata import StrataNet

# Download pretrained weights
path  = hf_hub_download(repo_id="emylton/strata-net", filename="aapl_net.pt")
model = StrataNet.load(path)

# Predict from normalised OHLCV window (30 candles)
import torch
from strata.net_trainer import _normalise_window

candles = [{"open": ..., "high": ..., "low": ..., "close": ..., "volume": ...}]  # 30 candles
x       = torch.tensor(_normalise_window(candles), dtype=torch.float32)  # (30, 5)
result  = model.predict_action(x)

print(result)
# {
#   "action":     "LONG",
#   "confidence": 0.71,
#   "regime":     "TRENDING",
#   "state": {
#       "bias":        0.82,   # interpretable — always in [-1, 1]
#       "momentum":    0.45,   # interpretable — always in [0, 1]
#       "trap_risk":   0.18,   # interpretable — always in [0, 1]
#       "uncertainty": 0.31,   # interpretable — always in [0, 1]
#   }
# }
```

### Train your own model (no manual labeling needed)

```python
from strata import StrataNet, StrataNetConfig, StrataNetTrainer, StrataNetDataset

# Your candles: list of OHLCV dicts, oldest → newest
candles = [{"open": ..., "high": ..., "low": ..., "close": ..., "volume": ...}, ...]

# Labels auto-generated by STRATA rule-based teacher (no manual labeling)
dataset = StrataNetDataset.from_candles(candles, seq_len=30, asset="AAPL")
trainer = StrataNetTrainer(asset="AAPL")
model   = trainer.train(dataset, epochs=30)

model.save("my_model.pt")
```

### Fine-tune from pretrained

```python
from huggingface_hub import hf_hub_download
from strata import StrataNet, StrataNetTrainer, StrataNetDataset

# Load pretrained base
path  = hf_hub_download(repo_id="emylton/strata-net", filename="aapl_net.pt")
model = StrataNet.load(path)

# Fine-tune on your own data
dataset = StrataNetDataset.from_candles(my_candles, seq_len=30, asset="AAPL")
trainer = StrataNetTrainer(model=model, lr=1e-4)   # lower LR for fine-tuning
model   = trainer.train(dataset, epochs=10)
```

---

## Architecture

```
Input: OHLCV window  (B, T, 5)
         │
         ▼
StrataEmbedding      learned OHLCV → semantic features
         │            Linear(5 → embed_dim) + LayerNorm + GELU
         ▼
StrataCoreCell  ×T   custom GRU-like recurrent cell
         │            — update gate z  (how much to update state)
         │            — reset gate r   (how much past to forget)
         │            — candidate h̃   projected to 4-dim
         │            — bounds enforced: tanh for bias, sigmoid for others
         ▼
StrataHead           hidden state → outputs
         │            Linear(4 → head_dim) + GELU
         │            → action logits  (3: LONG/SHORT/HOLD)
         │            → confidence     (1: sigmoid)
         │            → regime logits  (4: TRENDING/RANGING/TRANSITIONING/CHOPPY)
         ▼
StrataNetOutput
```

---

## Training Methodology: Teacher-Student Distillation

StrataNet uses **knowledge distillation from a rule-based teacher** — no manual
price labeling required:

1. **Teacher**: STRATA rule-based state machine processes OHLCV windows and
   generates action labels (LONG/SHORT/HOLD) and regime labels using explicit,
   auditable rules.
2. **Student**: StrataNet learns to replicate the teacher's decisions while
   discovering its own compact representation in the 4-dim hidden state.
3. **Result**: A neural network that generalises the teacher's pattern recognition
   while being faster (single forward pass, no iterative state updates).

---

## Tick-Level Sensing (v2.6+)

If your data includes bid/ask prices, STRATA automatically upgrades from
**reactive** (volume-based) to **anticipatory** (spread-based) liquidity sensing:

```python
# Add bid/ask to candles — sense() auto-detects and uses spread
candle = {
    "open": 150.0, "high": 150.5, "low": 149.8, "close": 150.2,
    "volume": 1_000_000,
    "bid": 150.18, "ask": 150.22,    # spread = 0.04 (2.7 bps)
}
from strata import sense
signals = sense([...window..., candle])
# signals["source"] == "spread"      <- anticipatory (before price moves)
# signals["liquidity_above"] = 0.61  <- elevated: spread widened vs history
```

---

## Citation

If you use STRATA in research or production, please cite:

```bibtex
@software{strata2024,
  author    = {emylton},
  title     = {STRATA: A Stateful Market Trading Architecture},
  year      = {2024},
  url       = {https://github.com/rafaelsistems/strata-market},
  version   = {2.6.0},
}
```

---

## License

MIT License. See [LICENSE](https://github.com/rafaelsistems/strata-market/blob/main/LICENSE).