Metadata-Version: 2.4
Name: sagan-xai
Version: 0.2.1
Summary: SEBI-Compliant Quantitative Trading Platform with automated thresholds and HITL logging.
Home-page: https://github.com/sagan-labs/sagan-xai
Author: Sagan Labs
Author-email: Sagan Labs <hello@sagan-docs.vercel.app>
License: MIT
Project-URL: Homepage, https://sagan-docs.vercel.app
Project-URL: Documentation, https://sagan-docs.vercel.app
Project-URL: Source, https://github.com/That-Tech-Geek/sagan
Project-URL: Bug Tracker, https://github.com/That-Tech-Geek/sagan/issues
Project-URL: Changelog, https://sagan-docs.vercel.app/changelog
Project-URL: PyPI, https://pypi.org/project/sagan-xai/
Keywords: trading,quantitative-finance,machine-learning,explainable-ai,pinn,temporal-fusion-transformer,mean-reversion,ensemble,deep-learning
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
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: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: tensorflow>=2.10
Requires-Dist: pandas>=1.5
Requires-Dist: numpy>=1.23
Requires-Dist: yfinance>=0.2
Requires-Dist: scikit-learn>=1.1
Requires-Dist: streamlit>=1.25
Requires-Dist: plotly>=5.15
Requires-Dist: cryptography
Requires-Dist: typer
Requires-Dist: snaptrade-python
Requires-Dist: schedule
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: mypy>=1.5; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Requires-Dist: mkdocs-material>=9.5; extra == "dev"
Requires-Dist: mkdocstrings[python]>=0.24; extra == "dev"
Provides-Extra: ci
Requires-Dist: pytest>=7.4; extra == "ci"
Requires-Dist: pytest-cov>=4.0; extra == "ci"
Requires-Dist: ruff>=0.4; extra == "ci"
Requires-Dist: mypy>=1.5; extra == "ci"
Requires-Dist: pandas>=1.5; extra == "ci"
Requires-Dist: numpy>=1.23; extra == "ci"
Requires-Dist: scikit-learn>=1.1; extra == "ci"
Requires-Dist: yfinance>=0.2; extra == "ci"
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.24; extra == "docs"
Requires-Dist: mkdocs-git-revision-date-localized-plugin>=1.2; extra == "docs"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# Sagan XAI

> **Explainable probabilistic ensemble for mean-reversion trading**

[![Python](https://img.shields.io/badge/python-3.8%2B-blue)](https://python.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

Sagan XAI combines three state-of-the-art techniques into a single, production-ready Python library:

| Component | Role |
|---|---|
| **Physics-Informed Neural Networks (PINN)** | Encode Ornstein–Uhlenbeck mean-reversion as a regularisation penalty |
| **Temporal Fusion Transformer (TFT)** | Multi-head self-attention over price return windows |
| **XAI-RL Override** | Flag low-confidence regime changes for human review |

---

## Installation

```bash
pip install sagan-xai
```

Or in editable mode from source:

```bash
git clone https://github.com/sagan-labs/sagan-xai
cd sagan-xai
pip install -e ".[dev]"
```

---

## Quick Start

### Python API

```python
import sagan

# Train a single ensemble across all tickers
model_id = sagan.train(["RELIANCE.NS", "TCS.NS", "HDFCBANK.NS"])

# Parallel training – one independent model per ticker
results = sagan.train_parallel_from_fetch(
    ["AAPL", "MSFT", "GOOGL"],
    num_processes=8,
)

# Predict using the latest saved model
signal = sagan.predict()
print(signal["signal"])        # "LONG" | "SHORT" | "NEUTRAL"
print(signal["confidence"])    # e.g. 0.74
print(signal["override"])      # True if confidence < threshold
```

### Command-Line Interface

```bash
# Train on Indian equities
sagan --train RELIANCE.NS TCS.NS INFY.NS

# Parallel training
sagan --train AAPL MSFT GOOGL --parallel --num-processes 8

# Get Trading Signal from latest model
sagan --predict

# Use a specific model
sagan --predict --model-id sagan_20240101_120000_abc123

# List all trained models
sagan --list
```

---

## Architecture

```
Input prices (T × N)
       │
       ▼
VariableSelectionNetwork   ← soft feature gating
       │
       ▼
TemporalFusionBlock        ← multi-head self-attention + FFN
       │
       ▼
 ┌─────┴──────┬──────────┐
 │            │          │
Buy head  Sell head  Hold head
 │            │          │
 └─────┬──────┴──────────┘
       │
       ▼
   Softmax ensemble  →  LONG / SHORT / NEUTRAL
       │
       ▼
  XAI-RL override check (confidence < threshold → flag)
```

**Loss function:**

```
L = BCE(y_true, logits) + λ · OU_penalty(logits)
```

where `OU_penalty` penalises deviation from 0.5 probability (mean-reversion prior).

---

## Configuration

All defaults live in `sagan.config`:

```python
from sagan import config

config.default_window = 10          # look-back window (days)
config.default_horizon = 3          # forward horizon for labelling
config.default_epochs = 30
config.pinn_lambda = 0.01           # strength of OU penalty
config.xai_confidence_threshold = 0.6  # override trigger
```

Models are stored in `~/.sagan/xai_models/` by default.

---

## Running Tests

```bash
pytest tests/ -v --cov=sagan
```

---

## API Reference

| Function | Description |
|---|---|
| `sagan.train(tickers, **kwargs)` | Train & save a new ensemble; returns `model_id` |
| `sagan.predict(model_id=None, tickers=None)` | Get trading signal from a saved model |
| `sagan.list_models()` | Return a DataFrame of all registered models |
| `sagan.train_parallel(tickers, prices_dict, ...)` | Parallel training from pre-fetched prices |
| `sagan.train_parallel_from_fetch(tickers, ...)` | Fetch + parallel train in one call |

---

## License

[MIT](LICENSE) © 2024 Sagan Labs
