Metadata-Version: 2.4
Name: stockvisionz-cli
Version: 0.1.7
Summary: StockVisionz CLI + platform backend
License-Expression: MIT
Project-URL: Homepage, https://stockvisionz.com
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: batch
Requires-Dist: pandas>=2.0; extra == "batch"
Requires-Dist: numpy>=1.24; extra == "batch"
Requires-Dist: psycopg[binary]>=3.1; extra == "batch"
Requires-Dist: python-dotenv>=1.0; extra == "batch"
Provides-Extra: ml
Requires-Dist: scikit-learn>=1.3; extra == "ml"
Requires-Dist: lightgbm>=4.0; extra == "ml"
Provides-Extra: cli
Provides-Extra: local
Requires-Dist: pandas>=2.0; extra == "local"
Requires-Dist: numpy>=1.24; extra == "local"
Requires-Dist: psycopg[binary]>=3.1; extra == "local"
Requires-Dist: python-dotenv>=1.0; extra == "local"
Requires-Dist: scikit-learn>=1.3; extra == "local"
Requires-Dist: lightgbm>=4.0; extra == "local"
Provides-Extra: hf
Requires-Dist: stable-baselines3>=2.0; extra == "hf"
Requires-Dist: gymnasium>=0.29; extra == "hf"
Requires-Dist: yfinance>=0.2; extra == "hf"
Requires-Dist: huggingface_hub>=0.20; extra == "hf"
Requires-Dist: pandas>=2.0; extra == "hf"
Requires-Dist: numpy>=1.24; extra == "hf"
Requires-Dist: scikit-learn>=1.3; extra == "hf"
Provides-Extra: dev
Requires-Dist: ruff>=0.6; extra == "dev"
Dynamic: license-file

# StockVisionz 🚀
### The No-Code Quant Analyst & Algorithmic Trading Research Platform

**StockVisionz** bridges the gap between sophisticated data science and everyday retail trading. It is a user-driven algorithmic trading research platform built for US equity markets that gives traders and researchers the infrastructure to explore, test, and compare advanced strategies on any US equity ticker—**without writing a single line of code.**

By treating the platform as a "No-Code Quant Analyst," the developer handles the complex heavy lifting (data pipelines, feature engineering, machine learning architectures, and vectorized backtesting) while the user steps into the role of a **Fund Manager**—selecting core predictive models, layering customized risk constraints, and analyzing institution-grade performance tearsheets.

---

## 🗺️ The Core Architecture & Interaction Model

The platform is designed around an intuitive three-step workflow that abstracts away data engineering and model training:

```
[ Step 1: Select Ticker & Base Model ]
       └── Search Ticker ➔ Pick Archetype (e.g., "The Momentum Chaser")

[ Step 2: Set Your Guardrails & Constraints ]
       └── Set Stop-Loss % ➔ Set Position Size ➔ Toggle "ML Smart Filter" (Meta-Labeling)

[ Step 3: Run, Validate & Compare ]
       └── Walk-Forward Validation ➔ Vectorized Backtest ➔ Visual Tearsheet View
```

1. **On-Demand Data Ingestion:** Enter any US equity ticker. If it doesn't exist in the system, StockVisionz automatically fetches historical price data, computes a comprehensive technical indicator suite, and prepares it for ingestion.
2. **On-Demand Execution:** Trigger backtests or complex machine learning model training sequences on the fly. All runs are fully versioned, logged, and persistent across user sessions for side-by-side comparison.

---

## 🤖 Pre-Built Quant Model Archetypes
As the developer, you provide a suite of advanced underlying models. Users select these models based on their core market philosophy:

| Model Archetype | Market Philosophy & What it Looks For | Under-the-Hood Technology |
| :--- | :--- | :--- |
| **The Momentum Chaser** | Identifies high-velocity breakout stocks and "rides the wave." | **XGBoost & Random Forest** trained on RSI, MACD, and Rate of Change (ROC). |
| **The Bargain Hunter** | Mean-reversion engine looking for stocks dropped "too far, too fast" for a bounce. | **Logistic Regression & SVM** evaluating Bollinger Band breaches and Z-scores. |
| **The Regime Adapter** | Detects overall market environments (Bull/Bear/Sideways) and alters entry filters. | **Hidden Markov Models (HMM)** & K-Means Clustering for structural regime shifts. |
| **The Crystal Ball** | Deep time-series sequence model attempting to predict next-week price directions. | **LSTM & GRU Neural Networks** trained on historical sequential OHLCV data. |
| **The Market Navigator** | Learns optimal buy/sell/hold execution paths through repeated environment interaction. | **Stable-Baselines3 (PPO / DQN)** Deep Reinforcement Learning agents optimizing cumulative reward. |

---

## 🎛️ The User's Constraint Layer (Strategy & Risk Guardrails)
Selecting a model is only half the process. To make it a true strategy, users apply their own behavioral constraints using simple sliders, toggles, and input boxes to define their individual risk tolerance:

* **Risk Controls (Capital Preservation):**
  * *Max Drawdown Stop:* Halts testing/trading if the equity curve drops more than `X%` from its peak.
  * *Hard Stop-Loss / Take-Profit:* Enforces deterministic exit thresholds per trade.
  * *Trailing Stop:* Locks in profits dynamically as the price moves in a favorable direction.
* **Portfolio Sizing & Execution Constraints:**
  * *Position Sizing:* Fixed dollar amounts (e.g., $5,000 per trade) vs. Dynamic equity allocation (e.g., `X%` of total portfolio).
  * *Max Holding Period:* Automatically flushes positions after `X` days to prevent capital from getting trapped in stagnant trades.
* **Market Environment Filters:**
  * *The "Bear Market Switch":* Global toggle restricting the underlying models to **Long-Only** trades *only* when the benchmark (S&P 500) is trading above its 200-day Simple Moving Average.

---

## 🧠 The Secret Sauce: "ML Smart Filter" (Meta-Labeling)
For users who want to combine traditional logic with advanced machine learning, StockVisionz introduces **Meta-Labeling**, visually abstracted as the **ML Smart Filter**:

1. The user defines a traditional, transparent, rule-based approach (e.g., a simple Price Dip/Support buyer).
2. They toggle the **ML Smart Filter** `ON`.
3. In the background, a machine learning model evaluates every historical instance where the rule-based strategy triggered a buy signal. The ML model learns the characteristics of past failures and systematically filters out future trade signals that carry a high mathematical probability of losing.
4. **The UI Output:** Users receive a clear, side-by-side performance breakdown: **My Pure Strategy** vs. **My Strategy + ML Smart Filter**, demonstrating precisely how machine learning adds value.

---

## 📊 Institutional-Grade Evaluation & Rigor
StockVisionz doesn't promise generic alpha; it provides the infrastructure to prove whether an idea holds merit under strict institutional validation standards:

* **Baseline-First Discipline:** Simpler models (e.g., SMA crossover or baseline Logistic Regression) run first. Complex models (LSTMs, RL Agents) must demonstrably outperform basic baselines to justify deployment.
* **Walk-Forward Validation:** All machine learning pipelines enforce rolling, non-overlapping walk-forward validation out-of-the-box to simulate authentic live trading conditions and eliminate hindsight bias.
* **Data Leakage Multi-Check:** An embedded validation layer prevents information from the future from leaking into training splits during feature scaling and indicator generation.
* **Vectorized Performance Tearsheets:** Powered by `vectorbt` for ultra-fast performance metrics, producing:
  * Total Return / CAGR / Alpha & Beta
  * Sharpe, Sortino, and Information Ratios
  * Max Drawdown duration and depth profiles
  * Monthly Return Heatmaps and historical interactive Equity Curves

---

## 🛠️ The Tech Stack

* **Time-Series Database:** PostgreSQL optimized with **TimescaleDB** for hyper-fast historical price retention and efficient ML feature extraction.
* **Backtesting Engine:** **vectorbt** for high-performance, parallelized, vectorized strategy evaluation.
* **Machine Learning Pipelines:** `scikit-learn`, `XGBoost` (GPU-accelerated), `PyTorch`, and `stable-baselines3`.
* **Data Pipeline Architecture:** Vendor-agnostic **Adapter Pattern** enabling seamless transitions or fallback states between market data providers (e.g., Alpaca, Polygon, Interactive Brokers) without breaking the core pipeline.
* **Frontend Dashboard:** **Next.js** (React) with **TypeScript**, styled elegantly via **Tailwind CSS**, and interactive visuals mapped through **Recharts**.

---

## 🤝 Support & Community
StockVisionz is developed and operated by **STOCKVISIONS**. 

* **Support / Inquiries:** support@stockvisionz.com
* **Documentation:** [Link to platform docs / wiki]

---

## CLI install (end users)

The `stockvisionz` command is intended to work on any user’s laptop without cloning this repo.

- **Recommended**: install via `pipx` (adds the command to PATH cleanly)

```powershell
pipx install "stockvisionz-cli[local]"
stockvisionz login
stockvisionz run --symbol AAPL --preset 1y
stockvisionz ingest AAPL
stockvisionz jobs show 42
stockvisionz save 42 --name "My run"
stockvisionz version
stockvisionz auth status
```

- **Local compute (runs ML on your machine)**:

```powershell
pipx install "stockvisionz[local]"
stockvisionz login
stockvisionz run --symbol AAPL --start 2023-01-27 --end 2023-10-21
```

After a successful run, the CLI prints a metrics summary and prompts to save the run to your account (visible in the web Lab saved-runs dock). Non-interactive options:

```powershell
stockvisionz run --symbol AAPL --start 2023-01-27 --end 2023-10-21 --save
stockvisionz run --symbol AAPL --start 2023-01-27 --end 2023-10-21 --no-save
stockvisionz run --symbol AAPL --start 2023-01-27 --end 2023-10-21 --json
stockvisionz run --symbol AAPL --start 2023-01-27 --end 2023-10-21 --save --name "My AAPL run"
```

### Test PyPI (pre-release)

Publish a test build:

```powershell
python -m build
python -m twine upload --repository testpypi dist/stockvisionz_cli-0.1.6*
pipx install --index-url https://test.pypi.org/simple/ --pip-args="--extra-index-url https://pypi.org/simple/" "stockvisionz-cli[local]==0.1.6"
```

The save endpoint (`POST /v1/lab/backtest/{jobId}/save`) lives in the API Lambda — deploy it (see [`AWS/README.md`](AWS/README.md)) before Test PyPI users upgrade to a CLI version that calls save.

The CLI uses a device-code flow: it prints a code + link, you approve in the web app, and the CLI stores a long-lived token.

## ⚖️ Legal Disclaimer
*StockVisionz is a research, backtesting, and simulation platform. All data, machine learning outputs, and backtesting metrics are provided for educational and research purposes only. Nothing on this platform constitutes investment advice, financial planning, or a solicitation to buy or sell securities. Past performance is no guarantee of future results.
