@vizzor/cli 0.10.0 → 0.11.0

package/README.md

@@ -91,6 +91,7 @@ Beyond price targets, Vizzor provides:
 | **pnpm** | >= 8.0 | Recommended (npm/yarn also work) |
 | **Python** | 3.x | Required by `better-sqlite3` native build |
 | **C++ compiler** | GCC / Clang / MSVC | Required by `better-sqlite3` native build |
+| **Docker** | >= 24 | Optional, for ML sidecar + PostgreSQL |
 
 Works on **macOS**, **Linux**, and **Windows**. No GPU required.
 
@@ -117,6 +118,13 @@ pnpm build
 pnpm link --global
 ```
 
+### Docker (Full Stack)
+
+```bash
+cp .env.example .env    # Configure API keys
+docker compose up -d     # Starts CLI + ML sidecar + PostgreSQL
+```
+
 ---
 
 ## Quick Start
@@ -204,6 +212,8 @@ vizzor ico list [options]           # ICO/IDO tracker
 vizzor config init                  # Initialize config
 vizzor config set <key> <value>     # Set config value
 vizzor config show                  # Show config
+vizzor wallet create|import|list|delete  # Wallet management
+vizzor backtest [options]           # Historical strategy backtest
 vizzor bot start [options]          # Start Discord/Telegram bots
 vizzor bot validate                 # Check bot token configuration
 ```
@@ -231,6 +241,7 @@ vizzor bot validate                 # Check bot token configuration
 | `/agent status <name>` | View status + recent decisions |
 | `/agent delete <name>` | Delete an agent |
 | `/agent strategies` | List available strategies |
+| `/backtest` | Run historical strategy backtest |
 | `/help` | Command reference |
 | `/clear` | Clear messages |
 | `/exit` | Quit |
@@ -306,6 +317,11 @@ Vizzor exposes **17+ tools** to the AI. During conversation, the AI autonomously
 | `create_agent` | Deploy autonomous prediction agent |
 | `list_agents` | List active agents |
 | `get_agent_status` | Agent status and decisions |
+| `run_backtest` | Historical strategy backtesting |
+| `get_ml_prediction` | ML model price prediction |
+| `get_ml_regime` | Market regime classification |
+| `get_ml_model_health` | ML sidecar health and model status |
+| `classify_user_intent` | AI-powered query intent detection |
 
 ### AI Providers
 
@@ -337,7 +353,121 @@ For providers without tool support (Ollama), Vizzor pre-fetches all relevant dat
 | **Fear & Greed** | Crypto Fear & Greed Index | Public |
 | **Pump.fun** | Solana meme coin launches | Public |
 
-All responses cached in SQLite with configurable TTL (5 min for market data, 1 hour for token info, 24 hours for contract code).
+All responses cached with configurable TTL (5 min for market data, 1 hour for token info, 24 hours for contract code).
+
+### Database Layer
+
+Dual-backend storage with automatic migration:
+
+| Backend | Use Case |
+|---------|----------|
+| **SQLite** | Default, zero-config local cache |
+| **PostgreSQL** | Multi-instance deployments, Docker stack |
+
+Data pipeline collectors run on configurable intervals, aggregating market snapshots, token metrics, and wallet activity into time-series tables for ML training and trend analysis.
+
+### ML Prediction Sidecar
+
+A Python FastAPI sidecar enhances predictions with trained models:
+
+| Model | Algorithm | Purpose |
+|-------|-----------|---------|
+| **Price Predictor** | LSTM | Short-term price direction |
+| **Signal Classifier** | Random Forest | Buy/sell/hold signal quality |
+| **Anomaly Detector** | Isolation Forest | Unusual market activity |
+| **Rug Detector** | GBM | Scam token identification |
+| **Wallet Classifier** | LSTM | Wallet behavior profiling |
+| **Sentiment NLP** | DistilBERT | News headline sentiment |
+
+Models fall back to heuristic scoring when the sidecar is unavailable. Start with Docker:
+
+```bash
+docker compose up ml-sidecar
+curl http://localhost:8000/health
+```
+
+### REST API
+
+Authenticated REST API exposing all Vizzor capabilities programmatically:
+
+```bash
+# Start the API server
+vizzor api start --port 3100
+
+# Create an API key
+vizzor api key create "my-app"
+
+# Endpoints
+GET  /health              # Health check (public)
+GET  /docs                # OpenAPI/Swagger UI (dev only)
+POST /scan                # Token security scan
+POST /trends              # Market trends
+POST /track               # Wallet forensics
+POST /predict             # AI prediction
+POST /audit               # Contract audit
+POST /v1/backtest         # Historical backtest
+GET  /v1/agents           # List agents
+POST /v1/agents           # Create agent
+POST /v1/agents/:name/start  # Start agent
+POST /v1/agents/:name/stop   # Stop agent
+GET  /v1/portfolio/:id    # Agent portfolio
+```
+
+All endpoints require `X-API-Key` header. Rate limited to 100 req/min per key. Keys are hashed with scrypt and stored locally.
+
+### Autonomous Agents v2
+
+Portfolio-aware trading agents with risk management:
+
+- **Portfolio Manager** — tracks positions, calculates P&L, manages allocation limits
+- **Risk System** — Kelly criterion position sizing, ATR-based stop losses, drawdown limits
+- **ML-Adaptive Strategy** — combines RSI, MACD, EMA, Bollinger, funding rate with ML regime detection
+- **Strategy Registry** — pluggable strategy system, easy to add custom strategies
+
+### Security & ZK
+
+- **AES-256-GCM encryption** for sensitive data at rest
+- **HMAC signatures** for API request integrity
+- **Audit logging** for security-critical operations
+- **ZK-proof chain adapters** for privacy-preserving verification
+- **Input sanitization** across all user-facing surfaces
+
+### n8n Workflow Automation
+
+14 pre-built n8n workflows for automated operations:
+
+| Workflow | Function |
+|----------|----------|
+| Data Collection | Scheduled market data ingestion |
+| Alert Pipeline | Real-time anomaly alerts |
+| ML Retraining | Periodic model retraining |
+| Agent Monitor | Agent health and decision tracking |
+| Daily Report | Automated portfolio summaries |
+| Anomaly Analysis | Deep-dive unusual activity |
+| Narrative Generator | Market narrative detection |
+| Portfolio Rebalancer | Automated rebalancing signals |
+| Strategy Tournament | Strategy backtesting comparison |
+| Arbitrage Scanner | Cross-DEX price divergence |
+
+```bash
+docker compose up -d  # Starts Vizzor + ML sidecar + PostgreSQL + n8n + Web Dashboard
+```
+
+### Extended ML Models
+
+v0.10 adds 7 new Python models to the sidecar:
+
+| Model | Algorithm | Purpose |
+|-------|-----------|---------|
+| **Trend Scorer** | XGBoost | Market trend strength scoring |
+| **TA Interpreter** | Random Forest | Technical analysis signal weighting |
+| **Strategy Bandit** | Contextual Bandit | Adaptive strategy selection |
+| **Regime Detector** | HMM | Market regime classification |
+| **Project Risk** | GBM | Comprehensive project risk scoring |
+| **Portfolio Optimizer** | Mean-Variance | Dynamic position sizing |
+| **Intent Classifier** | DistilBERT | User query intent detection |
+
+All 13 models integrated across 14 TypeScript modules with graceful fallback to heuristics. v0.11 adds model training pipeline (`POST /train`, `POST /evaluate`) and wires remaining ML modules.
 
 ---
 
@@ -357,8 +487,70 @@ Autonomous prediction agents that run a continuous **think -> analyze -> decide
 |----------|---------|-------|------|
 | **Momentum** | RSI + MACD + Bollinger + Funding | RSI crosses above 30 + bullish MACD | RSI > 70 + bearish divergence |
 | **Trend-Following** | EMA Crossover + OBV + Fear & Greed | Golden cross + rising volume | Death cross |
+| **ML-Adaptive** | All TA + Funding + Fear & Greed + Regime | ML composite score > threshold | ML signal reversal + stop loss |
+
+> Agents can run in **alert-only mode** or with **live trade execution** via DEX integration.
+
+### Trade Execution (v0.11)
+
+On-chain trade execution with safety controls:
+
+- **Wallet Manager** — encrypted private key storage (AES-256-GCM + scrypt) at `~/.vizzor/wallets/`
+- **DEX Router** — Uniswap V3 SwapRouter02 integration for token swaps
+- **Slippage Protection** — configurable max slippage (default 0.5%)
+- **Dry-Run Mode** — simulate trades without executing (default: on)
+- **Gas Estimation** — automatic gas estimation with configurable multiplier
+
+```bash
+vizzor wallet create           # Create encrypted wallet
+vizzor wallet import           # Import existing private key
+vizzor wallet list             # List managed wallets
+```
+
+### Backtesting Engine (v0.11)
+
+Historical strategy simulation with walk-forward analysis:
+
+```bash
+vizzor backtest --strategy momentum --pair BTCUSDT --from 2024-01-01 --to 2024-12-31
+```
+
+- Run any strategy against historical kline data
+- Metrics: total return, win rate, profit factor, Sharpe ratio, max drawdown
+- Equity curve and drawdown visualization
+- Walk-forward analysis with rolling train/test windows
+- Available via CLI, TUI (`/backtest`), AI tool, and REST API (`POST /v1/backtest`)
+
+### Real-time WebSocket Feeds (v0.11)
+
+Live market data via Binance WebSocket streams:
+
+- Trade, kline, and ticker streams with auto-reconnect
+- Connection pooling (up to 5 connections, 1024 streams each)
+- In-memory price cache for instant access
+- Agent engine prefers WebSocket data over REST polling
+
+### Web Dashboard (v0.11)
+
+Next.js 15 web dashboard at `http://localhost:3001`:
+
+- **Dashboard** — market overview, ML status, agent summary
+- **Predictions** — candlestick charts with price predictions
+- **Agents** — create, start/stop, and monitor agents
+- **Portfolio** — positions, trade history, performance metrics
+- **Settings** — API configuration
+
+```bash
+docker compose up web           # Start dashboard on port 3001
+```
+
+### Training Pipeline (v0.11)
+
+Model training and evaluation via the ML sidecar:
 
-> v0.3.0: Agents operate in **alert-only mode** -- they log decisions and emit signals but do not execute on-chain transactions.
+- `POST /train` — train rug detector, trend scorer, regime classifier, sentiment models
+- `POST /evaluate` — evaluate model accuracy on held-out test sets
+- Data loaders for PostgreSQL-backed labeled datasets
 
 ---
 
@@ -373,7 +565,10 @@ Autonomous prediction agents that run a continuous **think -> analyze -> decide
 | Base | Live | GoPlus |
 | BSC | Live | GoPlus |
 | Avalanche | Live | GoPlus |
-| Solana | Live (DEX + GoPlus) | GoPlus |
+| Solana | Live | GoPlus |
+| Sui | Live | GoPlus |
+| Aptos | Live | GoPlus |
+| TON | Live | GoPlus |
 
 New chains are added by implementing the `ChainAdapter` interface.
 
@@ -444,7 +639,7 @@ pnpm dev              # Dev mode (tsx)
 pnpm build            # Build (tsup)
 pnpm lint             # ESLint
 pnpm typecheck        # TypeScript strict
-pnpm test             # Vitest (164 tests, 19 suites)
+pnpm test             # Vitest
 pnpm test:coverage    # With coverage
 ```
 
@@ -456,8 +651,11 @@ pnpm test:coverage    # With coverage
 | CLI | Commander.js |
 | TUI | Ink (React for terminals) |
 | AI | Anthropic SDK, OpenAI SDK, Google GenAI, Ollama |
-| Blockchain | viem (EVM), plugin adapter system |
-| Database | better-sqlite3 with TTL cache |
+| Blockchain | viem (EVM), Solana, Sui, Aptos, TON adapters |
+| Dashboard | Next.js 15, React 19, Tailwind CSS 4 |
+| Database | better-sqlite3 + PostgreSQL (pg) |
+| ML Sidecar | Python FastAPI, scikit-learn, PyTorch |
+| API | Fastify + Swagger/OpenAPI |
 | Bots | discord.js, grammY |
 | Build | tsup |
 | Test | Vitest |