Metadata-Version: 2.4
Name: trustworthy-stock-intelligence
Version: 0.4.2
Summary: Leakage-aware and trust-aware tools for stock drawdown-risk analysis.
Author: KageRyo
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/KageRyo/trustworthy-stock-intelligence
Project-URL: Repository, https://github.com/KageRyo/trustworthy-stock-intelligence
Project-URL: Documentation, https://github.com/KageRyo/trustworthy-stock-intelligence/tree/main/docs
Project-URL: Issues, https://github.com/KageRyo/trustworthy-stock-intelligence/issues
Project-URL: Changelog, https://github.com/KageRyo/trustworthy-stock-intelligence/blob/main/CHANGELOG.md
Keywords: stock risk,drawdown,financial machine learning,calibration,uncertainty,trustworthy ai
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.26
Requires-Dist: pandas>=2.1
Requires-Dist: joblib>=1.3
Requires-Dist: scikit-learn>=1.4
Requires-Dist: pydantic>=2.7
Provides-Extra: models
Requires-Dist: xgboost>=2.0; extra == "models"
Requires-Dist: lightgbm>=4.0; extra == "models"
Requires-Dist: imbalanced-learn>=0.12; extra == "models"
Requires-Dist: statsmodels>=0.14; extra == "models"
Requires-Dist: optuna>=3.6; extra == "models"
Provides-Extra: explainability
Requires-Dist: shap>=0.45; extra == "explainability"
Provides-Extra: viz
Requires-Dist: matplotlib>=3.8; extra == "viz"
Requires-Dist: seaborn>=0.13; extra == "viz"
Requires-Dist: plotly>=5.20; extra == "viz"
Provides-Extra: notebooks
Requires-Dist: jupyterlab>=4.2; extra == "notebooks"
Requires-Dist: notebook>=7.2; extra == "notebooks"
Requires-Dist: ipykernel>=6.29; extra == "notebooks"
Provides-Extra: data
Requires-Dist: lxml>=5.0; extra == "data"
Requires-Dist: pandas-market-calendars>=4.4; extra == "data"
Requires-Dist: requests>=2.31; extra == "data"
Requires-Dist: ta>=0.11; extra == "data"
Requires-Dist: yfinance>=0.2; extra == "data"
Provides-Extra: db
Requires-Dist: psycopg[binary]>=3.2; extra == "db"
Provides-Extra: deep
Requires-Dist: torch<2.12,>=2.11; extra == "deep"
Requires-Dist: torchvision<0.27,>=0.26; extra == "deep"
Requires-Dist: torchaudio<2.12,>=2.11; extra == "deep"
Requires-Dist: tensorboard>=2.16; extra == "deep"
Provides-Extra: deep-cu126
Requires-Dist: torch<2.12,>=2.11; extra == "deep-cu126"
Requires-Dist: torchvision<0.27,>=0.26; extra == "deep-cu126"
Requires-Dist: torchaudio<2.12,>=2.11; extra == "deep-cu126"
Requires-Dist: tensorboard>=2.16; extra == "deep-cu126"
Provides-Extra: dashboard
Requires-Dist: streamlit>=1.36; extra == "dashboard"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff<0.17,>=0.15; extra == "dev"
Requires-Dist: twine>=6.0; extra == "dev"
Requires-Dist: uv>=0.11; extra == "dev"
Dynamic: license-file

# Trustworthy Stock Intelligence

`trustworthy-stock-intelligence` is a Python package for leakage-aware stock drawdown-risk research.
It provides reusable feature, labeling, baseline-model, evaluation, uncertainty, trust-score, and
serving-schema primitives.

This distribution is the Python/ML core of the larger
[Trustworthy Stock Intelligence repository](https://github.com/KageRyo/trustworthy-stock-intelligence).
The Go API, PostgreSQL workers, TypeScript dashboard, Docker Compose stack, and market-data
artifacts are separate surfaces and are not included in this wheel.

## Install

```bash
python -m pip install trustworthy-stock-intelligence
```

Install provider and universe-ingestion support only when needed:

```bash
python -m pip install "trustworthy-stock-intelligence[data]"
```

Optional model/runtime groups are explicit:

```bash
python -m pip install "trustworthy-stock-intelligence[models]"
python -m pip install "trustworthy-stock-intelligence[deep]"
python -m pip install "trustworthy-stock-intelligence[db]"
```

The `deep` extra records the PyTorch dependency. For CUDA installations, follow the
[GPU environment guide](https://github.com/KageRyo/trustworthy-stock-intelligence/blob/main/docs/environment.md)
and install the wheel index matching the target host.

## Python API

```python
from tsi import (
    add_future_drawdown_label,
    build_technical_features,
    classification_metrics,
    read_ohlcv_csv,
)
import numpy as np

ohlcv = read_ohlcv_csv("ohlcv.csv")
featured = build_technical_features(ohlcv)
labeled = add_future_drawdown_label(featured, horizon=5, threshold=-0.05)

# Future labels must be separated with a leakage-aware temporal split before
# training or evaluating a model. A metrics call receives model probabilities:
metrics = classification_metrics(
    np.array([0, 1]),
    np.array([0.10, 0.90]),
)
```

Top-level exports include `LogisticRiskModel`, `TreeRiskModel`, technical features, future drawdown
labels, warning-level selection, calibration-aware metrics, uncertainty functions, trust scores, and
Pydantic serving schemas. Ticker symbols remain strings, so values such as `0050` and `00981A`
retain their leading zeroes and suffixes.

## CLI

The package exposes a deterministic local CLI. It reads local artifacts and does not silently call a
provider or start the full application:

```bash
tsi --version
tsi inspect-csv path/to/ohlcv.csv --json
tsi evaluate predictions.csv \
  --label-column risk_label \
  --probability-column calibrated_risk_probability \
  --threshold 0.25 \
  --json
```

## Scope and limitations

This package supports trustworthy-ML engineering and reproducible pilot research. It is not
investment advice, a price-prediction guarantee, an automated trading system, or evidence of
externally validated performance. Labels intentionally use future observations; temporal splitting,
calibration protocols, data provenance, provider terms, and survivorship-bias limitations remain the
responsibility of each experiment.

See the
[package guide](https://github.com/KageRyo/trustworthy-stock-intelligence/blob/main/docs/python-package.md)
for the full API boundary, extras, local checks, and release process. See the
[main README](https://github.com/KageRyo/trustworthy-stock-intelligence#readme) for the complete
operational prototype.
