sagan-trade 0.2.4__tar.gz

sagan_trade-0.2.4/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Changelog
+
+All notable changes to **Sagan XAI** will be documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [0.2.1] – 2026-04-15
+
+### Fixed
+- Dashboard SyntaxError: Fixed `nonlocal` scoping issue in `sagan/app.py` that occurred when using certain Python versions or execution contexts.
+
+## [0.2.0] – 2026-04-15
+
+### Added
+- SEBI Compliance Engine: Dual export of signals to `.md` and `.json`.
+- Automated Threshold Optimization: Model-generated RSI and Volatility boundaries for 2000+ NSE stocks.
+- HITL Audit Logic: Local SQLite database (`sagan.db`) recording all actions and model justifications.
+- Gating-Driven Conflict resolution: Using TFT Variable Selection Network (VSN) weights to manage signal discrepancies.
+- Consolidated Typer CLI: New commands `userlogs`, `metrics`, and `dash`.
+
+## [0.0.1] – 2026-04-15
+
+### Changed
+- **Completely removed paywall and credit tracking**: Firestore-based billing and tiered feature gating have been stripped. The library is now fully open and free.
+- **Fixed TensorFlow retracing issue**: Optimized prediction pipeline to use direct model calls and added an LRU cache for model loading, resolving expensive tracing warnings during inference.
+- **Reset versioning**: Reset package version to `0.0.1` as per state transition.
+
+### Removed
+- `sagan.billing` module and all related Firestore/sync logic.
+- `auth`, `sync`, and `usage` CLI commands.
+- Dependencies: `authlib`, `python-jose`, `httpx`.
+
+---
+
+## [0.1.0] – 2024-04-11
+
+### Added
+- **`ExplainableEnsemble`** – three-head TFT model (buy / sell / hold) with PINN mean-reversion loss.
+- **`train()`** – convenience wrapper that fetches, trains, and registers an ensemble in one call.
+- **`predict()`** – generates a `LONG / SHORT / NEUTRAL` signal with confidence and XAI override flag.
+- **`batch_predict()`** – compares signals across multiple saved model IDs.
+- **`train_parallel()`** / **`train_parallel_from_fetch()`** – multiprocessing dispatch for training one model per ticker simultaneously.
+- **`list_models()`** / **`delete_model()`** / **`export_model()`** – full registry lifecycle management.
+- **`SaganConfig`** – centralised configuration dataclass with `from_env()` and `from_dict()` factory methods.
+- **`setup_logging()`** – configurable logger helper.
+- **`sharpe_ratio()`**, **`max_drawdown()`**, **`annualised_return()`**, **`calmar_ratio()`** – reusable financial metrics.
+- **Custom exception hierarchy**: `SaganError`, `ModelNotFoundError`, `InsufficientDataError`, `FetchError`, `ConfigurationError`, `RegistryCorruptedError`.
+- **CLI** (`sagan --train`, `--predict`, `--list`, `--parallel`, `--model-id`, `--epochs`, `--window`, `--horizon`).
+- **Full MkDocs Material documentation** hosted at <https://sagan-docs.vercel.app>.
+- **GitHub Actions** CI (lint + type-check + test) and PyPI publish workflows.
+- `py.typed` marker for PEP 561 compliance.
+
+### Notes
+- Initial public alpha. API may evolve before `1.0.0`.
+- TensorFlow ≥ 2.10 required; GPU is auto-detected but not required.
+
+[0.1.0]: https://github.com/sagan-labs/sagan/releases/tag/v0.1.0

sagan_trade-0.2.4/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Sagan Labs
+
+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.

sagan_trade-0.2.4/MANIFEST.in

@@ -0,0 +1,10 @@
+include README.md
+include LICENSE
+include CHANGELOG.md
+include pyproject.toml
+include requirements.txt
+recursive-include sagan *.py py.typed
+recursive-include docs *.md *.yml *.png *.svg
+recursive-exclude * __pycache__
+recursive-exclude * *.pyc
+recursive-exclude * *.pyo

sagan_trade-0.2.4/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: sagan-trade
+Version: 0.2.4
+Summary: Strategic 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: 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
+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]"
+```
+
+---
+
+## 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"], 
+    target_r2=0.95,
+    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 --r2 0.95 --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

sagan_trade-0.2.4/README.md

@@ -0,0 +1,102 @@
+# 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]"
+```
+
+---
+
+## 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"], 
+    target_r2=0.95,
+    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 --r2 0.95 --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

sagan_trade-0.2.4/docs/api/cli.md

@@ -0,0 +1,78 @@
+# CLI Reference
+
+The `sagan` command-line tool is installed automatically with the package.
+
+```bash
+sagan --help
+```
+
+---
+
+## Commands
+
+### `--train`
+
+Train a new ensemble on one or more tickers.
+
+```bash
+sagan --train RELIANCE.NS TCS.NS HDFCBANK.NS
+```
+
+| Flag | Type | Default | Description |
+|---|---|---|---|
+| `--train TICKERS…` | `str+` | — | **Required.** Ticker symbols |
+| `--years INT` | int | 5 | Years of historical data |
+| `--window INT` | int | 10 | Look-back window (days) |
+| `--horizon INT` | int | 3 | Forward horizon for labelling |
+| `--epochs INT` | int | 30 | Max training epochs |
+| `--parallel` | flag | off | Train one model per ticker in parallel |
+| `--num-processes INT` | int | 12 | Parallel worker processes |
+
+---
+
+### `--predict`
+
+Generate a trading signal using the latest (or a specific) saved model.
+
+```bash
+sagan --predict
+sagan --predict --model-id sagan_20240411_120000_abc123
+```
+
+| Flag | Type | Default | Description |
+|---|---|---|---|
+| `--predict` | flag | — | **Required.** Activate predict mode |
+| `--model-id STR` | str | latest | Specific model to query |
+
+---
+
+### `--list`
+
+Display a table of all registered models.
+
+```bash
+sagan --list
+```
+
+Output columns: `model_id`, `tickers`, `val_sharpe`, `override_fraction`, `created_at`.
+
+---
+
+## Examples
+
+```bash
+# Train on NSE blue-chips, 5 years
+sagan --train RELIANCE.NS TCS.NS INFY.NS HDFCBANK.NS --years 5
+
+# Parallel training on US tech (8 workers)
+sagan --train AAPL MSFT GOOGL AMZN META --parallel --num-processes 8
+
+# Aggressive hyper-params
+sagan --train AAPL --window 20 --horizon 5 --epochs 100
+
+# Predict with a specific model
+sagan --predict --model-id sagan_20240411_120000_abc123
+
+# List all models
+sagan --list
+```

sagan_trade-0.2.4/docs/api/config.md

@@ -0,0 +1,73 @@
+# Config
+
+The `sagan.config` module exposes the :class:`~sagan.config.SaganConfig` dataclass
+and the module-level `config` singleton that all Sagan modules share.
+
+---
+
+## SaganConfig
+
+::: sagan.config.SaganConfig
+
+---
+
+## config (singleton)
+
+```python
+from sagan import config
+
+# Inspect defaults
+print(config.default_window)             # 10
+print(config.xai_confidence_threshold)  # 0.6
+print(config.models_dir)                # ~/.sagan/xai_models
+
+# Mutate for the current session
+config.default_epochs = 50
+config.pinn_lambda = 0.005
+```
+
+---
+
+## Environment Variables
+
+`SaganConfig.from_env()` reads the following variables:
+
+| Variable | Field | Type |
+|---|---|---|
+| `SAGAN_HOME_DIR` | `home_dir` | `Path` |
+| `SAGAN_MODELS_DIR` | `models_dir` | `Path` |
+| `SAGAN_DEFAULT_WINDOW` | `default_window` | `int` |
+| `SAGAN_DEFAULT_HORIZON` | `default_horizon` | `int` |
+| `SAGAN_DEFAULT_EPOCHS` | `default_epochs` | `int` |
+| `SAGAN_DEFAULT_HEAD_DIM` | `default_head_dim` | `int` |
+| `SAGAN_DEFAULT_NUM_HEADS` | `default_num_heads` | `int` |
+| `SAGAN_DEFAULT_FF_DIM` | `default_ff_dim` | `int` |
+| `SAGAN_DEFAULT_DROPOUT` | `default_dropout` | `float` |
+| `SAGAN_DEFAULT_THRESHOLD` | `default_threshold` | `float` |
+| `SAGAN_PINN_LAMBDA` | `pinn_lambda` | `float` |
+| `SAGAN_XAI_CONFIDENCE_THRESHOLD` | `xai_confidence_threshold` | `float` |
+| `SAGAN_REGIME_CHANGE_THRESHOLD` | `regime_change_threshold` | `float` |
+
+---
+
+## Example: Programmatic override
+
+```python
+from sagan.config import SaganConfig
+import sagan
+
+# Override via dict
+cfg = SaganConfig.from_dict({
+    "default_window": 20,
+    "default_epochs": 50,
+    "pinn_lambda": 0.005,
+})
+
+# Use with ExplainableEnsemble
+from sagan import ExplainableEnsemble
+ens = ExplainableEnsemble(
+    ["AAPL"],
+    window=cfg.default_window,
+    epochs=cfg.default_epochs,
+)
+```

sagan_trade-0.2.4/docs/api/data.md

@@ -0,0 +1,52 @@
+# Data
+
+The `sagan.data` module handles price data acquisition and supervised dataset preparation.
+
+---
+
+## fetch_prices
+
+::: sagan.data.fetch_prices
+
+---
+
+## validate_tickers
+
+::: sagan.data.validate_tickers
+
+---
+
+## prepare_probabilistic_data
+
+::: sagan.data.prepare_probabilistic_data
+
+---
+
+## Labelling scheme
+
+Given a forward return $\bar{r}$ and a threshold $\delta$:
+
+| Condition | Label | Class index |
+|---|---|---|
+| $\bar{r} > \delta$ | **BUY** | 0 |
+| $\bar{r} < -\delta$ | **SELL** | 1 |
+| $-\delta \le \bar{r} \le \delta$ | **HOLD** | 2 |
+
+The one-hot label vector `y_probs[i]` has shape `(3,)` and sums to 1.
+
+---
+
+## Example: Manual data preparation
+
+```python
+from sagan.data import fetch_prices, prepare_probabilistic_data
+
+prices = fetch_prices(["RELIANCE.NS", "TCS.NS"], years=3)
+X, y_probs, y_ret, symbols, n_stocks = prepare_probabilistic_data(
+    prices, window=10, horizon=3, threshold=0.01
+)
+
+print(X.shape)        # (N, 10, 2)
+print(y_probs.shape)  # (N, 3)
+print(symbols)        # ['RELIANCE.NS', 'TCS.NS']
+```

sagan_trade-0.2.4/docs/api/ensemble.md

@@ -0,0 +1,16 @@
+# Ensemble
+
+The `sagan.ensemble` module contains the :class:`~sagan.ensemble.ExplainableEnsemble`
+class and the :func:`~sagan.ensemble.train` convenience function.
+
+---
+
+## ExplainableEnsemble
+
+::: sagan.ensemble.ExplainableEnsemble
+
+---
+
+## train
+
+::: sagan.ensemble.train

sagan_trade-0.2.4/docs/api/exceptions.md

@@ -0,0 +1,77 @@
+# Exceptions
+
+All Sagan exceptions inherit from :class:`~sagan.exceptions.SaganError`,
+allowing callers to catch any library error with a single `except SaganError`.
+
+---
+
+## Hierarchy
+
+```
+SaganError
+├── ModelNotFoundError
+├── InsufficientDataError
+├── FetchError
+├── ConfigurationError
+└── RegistryCorruptedError
+```
+
+---
+
+## SaganError
+
+::: sagan.exceptions.SaganError
+
+---
+
+## ModelNotFoundError
+
+::: sagan.exceptions.ModelNotFoundError
+
+---
+
+## InsufficientDataError
+
+::: sagan.exceptions.InsufficientDataError
+
+---
+
+## FetchError
+
+::: sagan.exceptions.FetchError
+
+---
+
+## ConfigurationError
+
+::: sagan.exceptions.ConfigurationError
+
+---
+
+## RegistryCorruptedError
+
+::: sagan.exceptions.RegistryCorruptedError
+
+---
+
+## Catching exceptions
+
+```python
+from sagan.exceptions import (
+    SaganError,
+    ModelNotFoundError,
+    FetchError,
+    InsufficientDataError,
+)
+import sagan
+
+# Catch all Sagan errors
+try:
+    result = sagan.predict(model_id="bad_id")
+except ModelNotFoundError as exc:
+    print(f"Model '{exc.model_id}' doesn't exist")
+except FetchError as exc:
+    print(f"Data fetch failed for {exc.tickers}")
+except SaganError as exc:
+    print(f"Sagan error: {exc}")
+```