Metadata-Version: 2.4
Name: sagan-trade
Version: 0.4.0
Summary: Strategic High-Throughput Symbolic Trading Engine with iterative R2 fitting and FunctionGemma discovery.
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: Repository, https://github.com/That-Tech-Geek/sagan-trade
Project-URL: Homepage, https://sagan-trade.vercel.app
Project-URL: Documentation, https://sagan-trade.vercel.app
Project-URL: Source, https://github.com/That-Tech-Geek/sagan-trade
Project-URL: Bug Tracker, https://github.com/That-Tech-Geek/sagan-trade/issues
Project-URL: Changelog, https://sagan-trade.vercel.app/changelog
Project-URL: PyPI, https://pypi.org/project/sagan-trade/
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-sdk
Requires-Dist: schedule
Requires-Dist: requests
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 Trade

> **High-throughput symbolic mathematical trading engine**

[![Python](https://img.shields.io/badge/python-3.9%2B-blue)](https://python.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![PyPI](https://img.shields.io/pypi/v/sagan-trade.svg)](https://pypi.org/project/sagan-trade/)

Sagan Trade replaces black-box neural networks with transparent, human-readable mathematical equations discovered via **FunctionGemma** (via Ollama). 

| Component | Role |
|---|---|
| **Symbolic Regressor** | Fits variables to R2 > 0.95 using Polynomial and Fourier basis functions. |
| **FunctionGemma** | AI architect that suggests optimal mathematical compositions of signals. |
| **Power Hub** | OS-level optimization for maximum throughput (Eco, Balanced, Turbo). |

---

## Installation

```bash
pip install sagan-trade
```

Or in editable mode from source:

```bash
git clone https://github.com/That-Tech-Geek/sagan-trade
cd sagan-trade
pip install -e ".[dev]"
```

---

## 📊 Conclusive Research & Benchmarking

Sagan Trade has been rigorously benchmarked against initial Deep Learning architectures (TFT-PINN). The results prove that **Symbolic Regression** provides superior risk-adjusted returns and institutional-grade transparency.

### Large-Scale Performance (10-Ticker Basket)
Benchmark conducted on a diversified basket: *AAPL, NVDA, TSLA, MSFT, GOOGL, META, AMD, GS, JPM, XOM*.

| Metric | Symbolic (Current) | TFT-PINN (Initial) | Buy & Hold |
|:---|:---|:---|:---|
| **Annualised Return** | **11.84%** | -37.52% | 52.19% |
| **Sharpe Ratio** | **2.46** | -2.47 | 2.39 |
| **Max Drawdown** | **-3.09%** | -35.10% | -12.06% |
| **Win Rate** | **57.78%** | 42.22% | N/A |

### Statistical Significance
- **P-Value**: **0.0206** ($p < 0.05$)
- **Verdict**: The Symbolic Engine is **statistically outperforming** legacy black-box ML models with high confidence.

> [!TIP]
> **Why the Math Model is safer**: As the number of assets increases, Sagan's `AlphaDesk` applies strict exposure scaling (capped at 2.5x - 3.0x). This results in a higher **Sharpe Ratio (2.46)** and significantly lower drawdown compared to standard equity portfolios, prioritizing **capital preservation** over raw beta exposure.

### Signal Fidelity & The "Fidelity Gap"
The engine utilizes a "Minimal Complexity First" principle to discover market invariants:
- **Price Signals**: Consistently achieve $R^2 > 0.90$ using 5th-degree polynomials.
- **Volume Signals**: Require Fourier series to capture structural cyclicality ($R^2 \approx 0.41$).

---

## Quick Start

### Python API

```python
import sagan

# Train a symbolic ensemble with high-accuracy math fitting
model_id = sagan.train(
    ["AAPL"], 
    signals=["Close", "Volume", "RSI"], 
    profile="turbo"
)

# Predict using the latest symbolic expression
result = sagan.predict()
print(result["signal"])     # "LONG" | "SHORT"
print(result["formula"])    # e.g. "(Close * 0.5) + log(Volume)"
```

### Command-Line Interface

```bash
# List available math signals for a ticker
sagan vars AAPL

# Train symbolic model
sagan train AAPL --signals Close,Volume --profile turbo

# Get Trading Signal
sagan predict
```

---

## Architecture

```
yfinance Data
       │
       ▼
[Parallel Fitting] → Each variable fitted to R2 > 0.95
       │
       ▼
[FunctionGemma]   → Suggests composite math formula
       │
       ▼
[Evaluation]      → Trend-based signal generation
```

---

## Configuration

All defaults live in `sagan.config`:

```python
from sagan import config

config.models_dir = "~/.sagan/models/"
```

---

## License

[MIT](LICENSE) © 2024 Sagan Labs
