@vizzor/cli 0.13.1 → 0.14.5

package/README.md

@@ -10,7 +10,7 @@
 
 <p align="center">
   <strong>See the future of crypto before it happens.</strong><br>
-  <em>AI-powered price predictions for coins, tokens, and currencies across every chain and DEX.</em>
+  <em>AI-powered price predictions with real dollar targets across every chain, token, and timeframe.</em>
 </p>
 
 <p align="center">
@@ -20,21 +20,21 @@
 </p>
 
 <p align="center">
-  <a href="#requirements">Requirements</a> &bull;
-  <a href="#installation">Install</a> &bull;
-  <a href="#quick-start">Quick Start</a> &bull;
-  <a href="#usage">Usage</a> &bull;
-  <a href="#agents">Agents</a> &bull;
+  <a href="#get-started-in-60-seconds">Get Started</a> &bull;
+  <a href="#features">Features</a> &bull;
+  <a href="#autonomous-agents">Agents</a> &bull;
   <a href="#web-dashboard">Dashboard</a> &bull;
-  <a href="#api-server">API</a> &bull;
+  <a href="#api">API</a> &bull;
+  <a href="#supported-chains">Chains</a> &bull;
+  <a href="#chronovisor-engine">ChronoVisor</a> &bull;
   <a href="#configuration">Config</a>
 </p>
 
 ---
 
-Vizzor is a crypto market prediction engine. It pulls live data from 7+ APIs, runs technical analysis on raw candles, reads derivatives positioning and market sentiment, then synthesizes price predictions with actual dollar targets across multiple timeframes — from 5 minutes to 3 months.
+Vizzor turns raw market data into actionable crypto predictions. It pulls live feeds from 15+ exchanges, runs technical analysis on real candles, reads derivatives positioning, tracks on-chain activity, and synthesizes everything into price predictions with actual dollar targets — from 5-minute scalps to 3-month outlooks.
 
-Ask about any coin, token, or currency. Vizzor fetches real-time data, computes signals, and gives you a prediction with numbers, not opinions.
+Ask about any coin, any token, any chain. Vizzor fetches the data, computes the signals, and gives you numbers — not opinions.
 
 ```
 vizzor
@@ -50,119 +50,54 @@ ETH at $2,112 | Bullish | Confidence: Medium-High
 
 ---
 
-## What It Does
-
-**Any tradable crypto asset.** BTC, ETH, SOL, meme coins, new DEX launches, tokens by contract address — if it has a price, Vizzor can analyze it.
-
-- **Price predictions** — bull/bear/likely targets across 9 timeframes (5m to 3 months), batch multi-horizon predictions in a single call
-- **ChronoVisor engine** — mathematical prediction system using Bayesian inference, certainty-factor algebra with weak signal dampening, first-order logic rules (17 base + 7 scalping), meta-reasoning, and continuous weight learning with feedback loops
-- **Alert-hit notifications** — toast banners for price target hits with training feedback (accuracy, streak, weight updates), ESC-to-dismiss, auto-dismiss after 5s
-- **Microstructure analysis** — market structure, FVGs, VWAP, volume delta, liquidation map, order book depth, S/R zones, squeeze detection
-- **Token security audits** — honeypot detection, tax analysis, mint/blacklist flags, rug pull indicators
-- **On-chain forensics** — wallet analysis, whale tracking, holder concentration, token flow patterns
-- **Blockchain fundamentals** — TVL, protocol revenue, developer activity, governance metrics, staking yields
-- **Derivatives positioning** — funding rates, open interest, long/short ratios from Binance Futures
-- **Prediction markets** — integrates Gamma and Polymarket data for market-implied probabilities
-- **Polymarket edge scanning** — compare ChronoVisor predictions against Polymarket odds, detect mispricings, execute trades via CLOB API
-- **Multi-exchange pricing** — aggregated prices from 15 exchanges (Binance, Coinbase, Kraken, OKX, Bybit, Gate.io, KuCoin, HTX, MEXC, Bitget, CoinGecko, CryptoCompare, DexScreener, GeckoTerminal, Jupiter) with VWAP/median aggregation and outlier detection
-- **Sentiment analysis** — Fear & Greed Index, news sentiment, buy/sell transaction ratios
-- **Trending discovery** — what tokens are moving right now across DexScreener and CoinGecko
-- **ICO tracking** — upcoming launches, fundraising rounds, investor data
-- **Notifications & alerts** — price alerts for all prediction types (directional + sideways breakout), prediction tracking, interactive alerts panel with dismiss-on-review for resolved predictions
-- **Autonomous agents** — set-and-forget trading agents with paper/live execution
-- **DeFi protocols** — Aave V3, Lido integrations with health monitoring and yield orchestration
+## Why Vizzor?
 
----
-
-## Requirements
-
-### Hardware
-
-| Component | Minimum | Recommended |
-|-----------|---------|-------------|
-| **CPU** | 2 cores | 4+ cores |
-| **RAM** | 2 GB | 4+ GB (8 GB if running ML sidecar) |
-| **Disk** | 500 MB | 2 GB (includes SQLite cache + ML models) |
-| **Network** | Stable internet | Low latency to Binance/CoinGecko APIs |
-| **GPU** | Not required | Not required (ML models are CPU-based) |
+Most crypto tools show you what already happened. Vizzor shows you what's likely to happen next.
 
-### Software
-
-| Dependency | Version | Notes |
-|------------|---------|-------|
-| **Node.js** | >= 20.0.0 | ES2022 target, ESM modules |
-| **pnpm** | >= 8.0 | Recommended package manager (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, web dashboard |
-
-Works on **macOS**, **Linux**, and **Windows**.
-
-### API Keys
-
-| Key | Required | Free Tier | Purpose |
-|-----|----------|-----------|---------|
-| `ANTHROPIC_API_KEY` | Yes (or use Ollama) | Pay-per-use | Claude AI — best prediction quality |
-| `ETHERSCAN_API_KEY` | Recommended | Yes | Transaction history, contract source |
-| `OPENAI_API_KEY` | No | Pay-per-use | GPT-4 as alternative provider |
-| `GOOGLE_API_KEY` | No | Free tier | Gemini as alternative provider |
-| `ALCHEMY_API_KEY` | No | Free tier | Premium RPC endpoints |
-| `COINGECKO_API_KEY` | No | Free tier | Extended market data |
-| `CRYPTOPANIC_API_KEY` | No | Free tier | News with sentiment |
-| `DISCORD_TOKEN` | No | Free | Discord bot |
-| `TELEGRAM_BOT_TOKEN` | No | Free | Telegram bot |
-| `POLYMARKET_PRIVATE_KEY` | No | N/A | Polymarket CLOB trading (edge execution) |
-
-**No API key at all?** Use Ollama with a local model — fully offline predictions (lower quality but free).
+- **Not a chart tool** — it's a prediction engine that synthesizes 6 independent signal types into one composite forecast
+- **Not a news aggregator** — it processes sentiment, derivatives, on-chain data, and technical indicators simultaneously
+- **Not a chatbot wrapper** — every prediction is backed by real market data from 15 exchanges, with traceable reasoning and confidence scores
+- **Works with everything** — BTC, ETH, SOL, meme coins, new DEX launches, tokens by contract address — if it has a price, Vizzor can predict it
 
 ---
 
-## Installation
-
-### npm (recommended)
+## Get Started in 60 Seconds
 
 ```bash
 npm install -g @vizzor/cli
+vizzor
 ```
 
-```bash
-# Or run directly without installing
-npx @vizzor/cli
-```
+That's it. Vizzor launches a guided setup wizard that walks you through:
+- Choosing your AI provider (Claude, GPT-4, Gemini, or local Ollama)
+- Setting up API keys
+- Picking your default chain
+- Learning the first commands
 
-### From Source
+### Start predicting
 
-```bash
-git clone https://github.com/7ayLabs/vizzor.git
-cd vizzor
-pnpm install
-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 + Web Dashboard
+> predict BTC price next week
+> analyze $PEPE security and price outlook
+> what's trending in crypto right now
+> full microstructure analysis for ETH
+> track wallet 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
+> audit contract 0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984
 ```
 
----
-
-## Quick Start
+### Better prediction accuracy
 
-### Option A: With Claude (best quality)
+After setup, follow these tips for the best results:
+- Run `/cosmos on` to enable full data pipeline
+- For intraday: focus on `BTC`, `ETH`, and `SOL` with `2h`, `3h`, `4h`, `6h` horizons
+- For scalping: focus on `BTC` and `ETH` with exact short horizons like `10m`, `20m`, `45m`
+- For long-range: ask for `7d`, `30d`, `90d`, or `1y` scenario ranges
+- Use `/precisions` to check tracked accuracy and `/playbook` for the full operating workflow
 
-```bash
-# 1. Set your Anthropic API key
-vizzor config set anthropicApiKey sk-ant-...
-# or: export ANTHROPIC_API_KEY=sk-ant-...
+### Alternative setups
 
-# 2. Launch
-vizzor
-```
-
-### Option B: With Ollama (free, local, offline)
+<details>
+<summary><b>Ollama (free, offline, no API key needed)</b></summary>
 
 ```bash
 # 1. Install Ollama: https://ollama.ai
@@ -175,8 +110,10 @@ vizzor config set ai.model llama3.2
 # 3. Launch
 vizzor
 ```
+</details>
 
-### Option C: With OpenAI or Gemini
+<details>
+<summary><b>OpenAI or Gemini</b></summary>
 
 ```bash
 vizzor config set ai.provider openai
@@ -185,27 +122,90 @@ vizzor config set openaiApiKey sk-...
 vizzor config set ai.provider gemini
 vizzor config set googleApiKey AI...
 ```
+</details>
 
-### Start asking
+<details>
+<summary><b>From source</b></summary>
 
+```bash
+git clone https://github.com/7ayLabs/vizzor.git
+cd vizzor
+pnpm install
+pnpm build
+pnpm link --global
 ```
-> predict BTC price next week
-> analyze $PEPE security and price outlook
-> what's trending in crypto right now
-> full microstructure analysis for ETH
-> track wallet 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
-> audit contract 0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984
+</details>
+
+<details>
+<summary><b>Docker (full stack)</b></summary>
+
+```bash
+cp .env.example .env     # Configure API keys
+docker compose up -d      # Starts CLI + ChronoVisor Engine + PostgreSQL + Web Dashboard
 ```
+</details>
 
 ---
 
-## Usage
+## Features
+
+### Predictions & Forecasting
+
+| Feature | What it does |
+|---------|-------------|
+| **Price predictions** | Bull/bear/likely targets across 9 timeframes (5m to 3 months), batch multi-horizon in a single call |
+| **ChronoVisor engine** | Mathematical prediction system: Bayesian inference, certainty-factor algebra with weak signal dampening, first-order logic rules (17 base + 7 scalping), meta-reasoning, and continuous weight learning with feedback loops |
+| **Alert-hit notifications** | Toast banners when price targets hit, with training feedback (accuracy, streak, weight updates), ESC-to-dismiss, auto-dismiss |
+| **Prediction markets** | Integrates Gamma and Polymarket data for market-implied probabilities |
+| **Polymarket edge scanning** | Compare ChronoVisor predictions vs Polymarket odds, detect mispricings, execute trades via CLOB API |
+
+### Market Intelligence
+
+| Feature | What it does |
+|---------|-------------|
+| **Multi-exchange pricing** | Aggregated prices from 15 exchanges (Binance, Coinbase, Kraken, OKX, Bybit, Gate.io, KuCoin, HTX, MEXC, Bitget, CoinGecko, CryptoCompare, DexScreener, GeckoTerminal, Jupiter) with VWAP/median aggregation and outlier detection |
+| **Microstructure analysis** | Market structure, FVGs, VWAP, volume delta, liquidation map, order book depth, S/R zones, squeeze detection |
+| **Derivatives positioning** | Funding rates, open interest, long/short ratios from Binance Futures |
+| **Sentiment analysis** | Fear & Greed Index + news sentiment + buy/sell transaction ratios |
+| **Trending discovery** | What's moving right now across DexScreener and CoinGecko |
+| **ICO tracking** | Upcoming launches, fundraising rounds, investor data |
+
+### Security & Forensics
+
+| Feature | What it does |
+|---------|-------------|
+| **Token security audits** | Honeypot detection, tax analysis, mint/blacklist flags, rug pull indicators |
+| **On-chain forensics** | Wallet analysis, whale tracking, holder concentration, token flow patterns |
+| **Smart contract audits** | Source code analysis, vulnerability detection, risk scoring |
+| **Blockchain fundamentals** | TVL, protocol revenue, developer activity, governance metrics, staking yields |
+
+### Trading & Automation
+
+| Feature | What it does |
+|---------|-------------|
+| **Autonomous agents** | Set-and-forget trading agents with paper/live execution and 5 built-in strategies |
+| **DeFi integrations** | Aave V3, Lido with health monitoring and yield orchestration |
+| **Backtesting** | Test strategies against historical data with full metrics (return, win rate, Sharpe, drawdown) |
+| **Wallet management** | AES-256-GCM encrypted wallets with scrypt key derivation |
+| **Notifications & alerts** | Price alerts for all prediction types (directional + sideways breakout), interactive alerts panel with dismiss-on-review |
+
+### Platforms
+
+| Platform | Description |
+|----------|-------------|
+| **Terminal (TUI)** | Interactive chat with live price ticker, streaming responses, and slash commands |
+| **Web Dashboard** | Next.js 15 — AI chat, markets, agents, portfolio, Polymarket, notifications |
+| **REST API** | Fastify + Swagger — 40+ endpoints with API key auth and rate limiting |
+| **Discord Bot** | Full command suite with AI-powered chat via @mention |
+| **Telegram Bot** | Full command suite with AI chat on any message |
+
+---
 
-### TUI (Terminal UI)
+## Terminal UI
 
-Launch with `vizzor`. Interactive chat with live price ticker, streaming responses, and slash commands.
+Launch with `vizzor`. Interactive chat with a live price ticker, streaming AI responses, and slash commands.
 
-**Price Ticker:** Arrow keys to navigate, **Enter** to trigger AI prediction, **Tab** to toggle focus.
+**Price Ticker:** Arrow keys to navigate, **Enter** to trigger prediction, **Tab** to toggle focus.
 
 | Command | Description |
 |---------|-------------|
@@ -223,6 +223,7 @@ Launch with `vizzor`. Interactive chat with live price ticker, streaming respons
 | `/chain [<id>]` | Show/switch chain |
 | `/provider` | Show current AI provider |
 | `/provider <name>` | Switch to `anthropic`, `openai`, `gemini`, `ollama` |
+| `/playbook` | Exact steps for better tracked prediction win rate |
 | `/agent create <name> [options]` | Create autonomous agent |
 | `/agent list` | List agents |
 | `/agent start <name>` | Start agent |
@@ -231,67 +232,48 @@ Launch with `vizzor`. Interactive chat with live price ticker, streaming respons
 | `/agent wallet <name>` | Show agent wallet balance |
 | `/agent trades <name>` | Show agent trade history |
 | `/backtest` | Historical strategy backtest |
+| `/chronovisor` | ChronoVisor engine status |
 | `/config` | Show config |
 | `/help` | Command reference |
 
-**Alerts Panel:** Type `/alerts` to open the interactive panel. Use **Up/Down** to navigate predictions and alerts, **Enter** to view full details (entry price, confidence, outcome, signal snapshot), **Escape** to close. Resolved predictions (HIT/MISS) are dismissed from the list when you exit their detail view. Pending predictions appear first; resolved predictions sort below them.
+**Alerts Panel:** Type `/alerts` to open the interactive panel. Use **Up/Down** to navigate predictions and alerts, **Enter** to view full details (entry price, confidence, outcome, signal snapshot), **Escape** to close. Resolved predictions remain available after review and become visually muted as seen history. Pending predictions appear first; resolved predictions sort below them.
 
 ### CLI Commands
 
 ```bash
 vizzor                              # Launch interactive TUI
-vizzor scan <token> [options]       # Token risk analysis
-vizzor trends [options]             # Market trends + top movers
-vizzor track <wallet> [options]     # Wallet forensics
-vizzor audit <contract> [options]   # Contract security audit
-vizzor ico list [options]           # ICO/IDO tracker
+vizzor setup                        # Reopen guided setup
 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 api start [--port 3100]      # Start REST API server
+vizzor serve [--port 7100]          # Start REST API server
 vizzor api key create "my-app"      # Create API key
+vizzor bot start [options]          # Start Discord/Telegram bots
+vizzor collect start [options]      # Start OHLCV data collection
+vizzor chronovisor setup            # Install ChronoVisor engine
+vizzor chronovisor start            # Start engine
+vizzor chronovisor stop             # Stop engine
+vizzor chronovisor status           # Engine health check
+vizzor predictions reset            # Reset prediction history
+vizzor health                      # Check config, API keys, and service connectivity
 ```
 
-### Discord Bot
-
-Requires `DISCORD_TOKEN`. Enable the `MESSAGE_CONTENT` privileged intent in the [Discord Developer Portal](https://discord.com/developers/applications).
-
-| Command | Description |
-|---------|-------------|
-| `/predict <symbol>` | AI prediction with signals |
-| `/scan <address>` | Token security scan |
-| `/trends` | Trending tokens |
-| `/track <wallet>` | Wallet forensics |
-| `/price <symbol>` | Live price |
-| `/audit <contract>` | Contract audit |
-| `/ico` | Upcoming launches |
-| `/agent_create` | Create agent |
-| *@mention* | AI-powered chat |
-
-### Telegram Bot
-
-Requires `TELEGRAM_BOT_TOKEN`.
-
-Same commands as Discord (`/predict`, `/scan`, `/trends`, `/track`, `/price`, `/audit`, `/ico`, `/agent_create`). Any text message triggers AI chat.
-
 ---
 
-## Agents
+## Autonomous Agents
 
-Autonomous prediction agents that run a continuous **think → analyze → decide → act** cycle.
+Set-and-forget trading agents that run a continuous **think > analyze > decide > act** cycle.
 
 ### Agent Requirements
 
 | Requirement | Details |
 |-------------|---------|
-| **AI Provider** | Any (Claude recommended for best decisions) |
+| **AI Provider** | Any supported provider (Claude recommended for best decisions) |
 | **Wallet** | Required for live trading; not needed for paper trading or alert-only |
 | **RPC Endpoint** | Required for live trading (default public RPCs or Alchemy) |
 | **Minimum Balance** | Agent-specific; configurable spending limits |
-| **Always-on Process** | Agent runs in a loop — needs a persistent process (terminal, tmux, Docker, etc.) |
+| **Always-on Process** | Agent runs in a loop — needs a persistent process (terminal, tmux, Docker) |
 
 ### Create and Run
 
@@ -311,15 +293,15 @@ Autonomous prediction agents that run a continuous **think → analyze → decid
 
 ### Execution Modes
 
-| Mode | Description | Wallet Required |
-|------|-------------|-----------------|
+| Mode | What happens | Wallet needed? |
+|------|-------------|----------------|
 | **Alert-only** | Generates signals, no trades | No |
 | **Paper trading** | Simulated trades with realistic slippage model | No |
 | **Live trading** | On-chain execution via DEX router | Yes |
 
 ### Strategies
 
-| Strategy | Signals | Best For |
+| Strategy | Signals | Best for |
 |----------|---------|----------|
 | **Momentum** | RSI + MACD + Bollinger + Funding | Short-term reversals |
 | **Trend-Following** | EMA Crossover + OBV + Fear & Greed | Swing trades |
@@ -356,21 +338,11 @@ vizzor wallet list             # List managed wallets
 
 Wallets are encrypted with AES-256-GCM (scrypt N=2^18) and stored at `~/.vizzor/wallets/`.
 
-### Backtesting
-
-Test strategies against historical data before going live:
-
-```bash
-vizzor backtest --strategy momentum --pair BTCUSDT --from 2024-01-01 --to 2024-12-31
-```
-
-Metrics: total return, win rate, profit factor, Sharpe ratio, max drawdown, equity curve.
-
 ---
 
 ## Web Dashboard
 
-Next.js 15 dashboard at `http://localhost:3001`.
+Next.js 15 dashboard with real-time market data, AI chat, and full portfolio tracking.
 
 ### Setup
 
@@ -384,24 +356,26 @@ pnpm install
 pnpm dev
 ```
 
-Requires the API server running (`vizzor api start`).
+Requires the API server running (`vizzor api start`). Available at `http://localhost:3001`.
 
 ### Pages
 
-- **AI Chat** — conversational interface with streaming, tool call progress, trade action cards, conversation persistence
-- **Dashboard** — market overview, Fear & Greed, sentiment, regime, trending tokens, news, prediction accuracy tracker
-- **Markets** — token analysis, wallet analyzer, on-chain intelligence
-- **Agents** — create, monitor, start/stop agents with paper/live mode, portfolio chart, trade history
-- **Portfolio** — positions, trade history, P&L metrics
-- **Notifications** — real-time notification panel with prediction detail modals, price alert management, desktop push notifications
-- **Polymarket** — edge scanner comparing ChronoVisor vs market odds, opportunity cards, position tracking, trade execution
-- **Settings** — API keys and provider configuration
+| Page | What you get |
+|------|-------------|
+| **AI Chat** | Conversational interface with streaming, tool call progress, trade action cards, conversation persistence |
+| **Dashboard** | Market overview, Fear & Greed, sentiment, regime, trending tokens, news, prediction accuracy tracker |
+| **Markets** | Token analysis, wallet analyzer, on-chain intelligence |
+| **Agents** | Create, monitor, start/stop agents with paper/live mode, portfolio chart, trade history |
+| **Portfolio** | Positions, trade history, P&L metrics |
+| **Notifications** | Real-time notification panel with prediction detail modals, price alert management, desktop push notifications |
+| **Polymarket** | Edge scanner comparing ChronoVisor vs market odds, opportunity cards, position tracking, trade execution |
+| **Settings** | API keys and provider configuration |
 
 ---
 
-## API Server
+## API
 
-REST API exposing all Vizzor capabilities programmatically.
+REST API exposing all Vizzor capabilities programmatically. Full Swagger documentation at `/docs`.
 
 ### Setup
 
@@ -425,7 +399,7 @@ GET  /v1/market/price/:symbol         # Price
 GET  /v1/market/prices?symbols=       # Batch prices
 GET  /v1/market/trending              # Trending tokens
 GET  /v1/market/fear-greed            # Fear & Greed Index
-GET  /v1/market/ml-health             # ML sidecar status
+GET  /v1/market/ml-health             # ChronoVisor engine status
 GET  /v1/market/trenches              # Trenches scanner
 GET  /v1/chronovisor/:symbol          # ChronoVisor prediction
 GET  /v1/chronovisor/predictions      # List all predictions
@@ -478,6 +452,41 @@ WS   /ws                              # WebSocket real-time push
 
 ---
 
+## ChronoVisor Engine
+
+The ChronoVisor engine is an optional Python-based prediction accelerator with 16 trained models that enhances Vizzor's predictions with ML. When unavailable, Vizzor falls back to its rule-based heuristics automatically — no setup required to start using Vizzor.
+
+### Quick setup
+
+```bash
+# Interactive wizard — detects Docker or Python, installs deps
+vizzor chronovisor setup
+
+# Start the engine
+vizzor chronovisor start
+
+# Check health
+vizzor chronovisor status
+```
+
+Or via Docker:
+
+```bash
+docker compose up chronovisor-engine
+curl http://localhost:7200/health
+```
+
+### Requirements
+
+| Component | Minimum |
+|-----------|---------|
+| **RAM** | 4 GB (8 GB recommended) |
+| **Disk** | 1 GB for models |
+| **Runtime** | Docker (recommended) or Python 3.11+ |
+| **GPU** | Not required — CPU-based by default |
+
+---
+
 ## Configuration
 
 Config at `~/.vizzor/config.yaml`. Environment variables override file values.
@@ -525,25 +534,72 @@ polymarket:
 
 ---
 
-## ML Sidecar (Optional)
+## Requirements
 
-Python FastAPI sidecar with 16 trained models for enhanced predictions. Falls back to heuristics when unavailable.
+### Hardware
 
-### Setup
+| Component | Minimum | Recommended |
+|-----------|---------|-------------|
+| **CPU** | 2 cores | 4+ cores |
+| **RAM** | 2 GB | 4+ GB (8 GB if running ChronoVisor engine) |
+| **Disk** | 500 MB | 2 GB (includes SQLite cache + ML models) |
+| **Network** | Stable internet | Low latency to Binance/CoinGecko APIs |
+| **GPU** | Not required | Not required (ML models are CPU-based) |
 
-```bash
-docker compose up ml-sidecar
-curl http://localhost:8000/health
-```
+### Software
 
-### Requirements
+| Dependency | Version | Notes |
+|------------|---------|-------|
+| **Node.js** | >= 20.0.0 | ES2022 target, ESM modules |
+| **pnpm** | >= 8.0 | Recommended package manager (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 ChronoVisor engine, PostgreSQL, web dashboard |
 
-| Component | Minimum |
-|-----------|---------|
-| **RAM** | 4 GB (8 GB recommended) |
-| **Disk** | 1 GB for models |
-| **Python** | 3.10+ |
-| **GPU** | Not required |
+Works on **macOS**, **Linux**, and **Windows**.
+
+### API Keys
+
+| Key | Required | Free Tier | Purpose |
+|-----|----------|-----------|---------|
+| `ANTHROPIC_API_KEY` | Yes (or use Ollama) | Pay-per-use | Claude AI — best prediction quality |
+| `ETHERSCAN_API_KEY` | Recommended | Yes | Transaction history, contract source |
+| `OPENAI_API_KEY` | No | Pay-per-use | GPT-4 as alternative provider |
+| `GOOGLE_API_KEY` | No | Free tier | Gemini as alternative provider |
+| `ALCHEMY_API_KEY` | No | Free tier | Premium RPC endpoints |
+| `COINGECKO_API_KEY` | No | Free tier | Extended market data |
+| `CRYPTOPANIC_API_KEY` | No | Free tier | News with sentiment |
+| `DISCORD_TOKEN` | No | Free | Discord bot |
+| `TELEGRAM_BOT_TOKEN` | No | Free | Telegram bot |
+| `POLYMARKET_PRIVATE_KEY` | No | N/A | Polymarket CLOB trading (edge execution) |
+
+**No API key at all?** Use Ollama with a local model — fully offline predictions (lower quality but free).
+
+---
+
+## Discord & Telegram
+
+### Discord Bot
+
+Requires `DISCORD_TOKEN`. Enable the `MESSAGE_CONTENT` privileged intent in the [Discord Developer Portal](https://discord.com/developers/applications).
+
+| Command | Description |
+|---------|-------------|
+| `/predict <symbol>` | AI prediction with signals |
+| `/scan <address>` | Token security scan |
+| `/trends` | Trending tokens |
+| `/track <wallet>` | Wallet forensics |
+| `/price <symbol>` | Live price |
+| `/audit <contract>` | Contract audit |
+| `/ico` | Upcoming launches |
+| `/agent_create` | Create agent |
+| *@mention* | AI-powered chat |
+
+### Telegram Bot
+
+Requires `TELEGRAM_BOT_TOKEN`.
+
+Same commands as Discord (`/predict`, `/scan`, `/trends`, `/track`, `/price`, `/audit`, `/ico`, `/agent_create`). Any text message triggers AI chat.
 
 ---
 
@@ -557,9 +613,11 @@ pnpm install
 pnpm dev              # Dev mode (tsx)
 pnpm build            # Build (tsup)
 pnpm lint             # ESLint
+pnpm format:check     # Prettier check
 pnpm typecheck        # TypeScript strict
 pnpm test             # Vitest
 pnpm test:coverage    # With coverage
+pnpm test:integration # Integration tests (needs API keys)
 ```
 
 ### Tech Stack
@@ -573,7 +631,7 @@ pnpm test:coverage    # With coverage
 | 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 |
+| ChronoVisor Engine | Python FastAPI, scikit-learn, PyTorch |
 | API | Fastify + Swagger/OpenAPI |
 | Bots | discord.js, grammY |
 | Build | tsup |

package/chronovisor-engine/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "vizzor-ml-sidecar"
+version = "0.14.5"
+description = "ML sidecar for Vizzor — LSTM, RF, Isolation Forest, Rug Detection, Wallet Classification, Sentiment NLP, Trend Scoring, TA Interpretation, Regime Detection, Strategy Bandit, Project Risk, Portfolio Optimization, Intent Classification"
+requires-python = ">=3.11"
+dependencies = [
+    "fastapi>=0.115.0",
+    "uvicorn[standard]>=0.34.0",
+    "torch>=2.5.0",
+    "scikit-learn>=1.6.0",
+    "psycopg2-binary>=2.9.10",
+    "numpy>=2.1.0",
+    "pandas>=2.2.0",
+    "joblib>=1.4.0",
+    "transformers>=4.40.0",
+    "xgboost>=2.0.0",
+    "hmmlearn>=0.3.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "httpx>=0.28.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src"]