stockvisionz-cli 0.1.7

StockVisionz CLI + platform backend

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: [e-mail]
• 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)

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):

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:

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:

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) 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.