mirror of
https://github.com/saymrwulf/alpha-arena.git
synced 2026-11-19 06:40:38 +00:00
docs: consolidate documentation and fix redundancies
- Add MACOS_APP_MANUAL.md reference to docs/index.md - Streamline QUICKSTART.md macOS section (reference full manual) - Update USER_MANUAL.md Quick Start to use ./alpha workflow - Clarify that python cli.py is for advanced usage - Fix venv naming consistency (.venv throughout)
This commit is contained in:
parent
1c66f3b254
commit
be7d27f663
3 changed files with 76 additions and 88 deletions
|
|
@ -99,69 +99,18 @@ ALPHA_HOST=0.0.0.0 ./alpha start
|
||||||
|
|
||||||
For a native macOS experience, use the menu bar app instead of terminal commands.
|
For a native macOS experience, use the menu bar app instead of terminal commands.
|
||||||
|
|
||||||
### Requirements
|
|
||||||
- macOS 13.0 or later
|
|
||||||
- Xcode 15.0+ (for building from source)
|
|
||||||
|
|
||||||
### Build & Install
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Build the app
|
# Build and install to /Applications
|
||||||
cd macos-app
|
cd macos-app && ./build.sh install
|
||||||
./build.sh
|
|
||||||
|
|
||||||
# Or build and install to /Applications
|
|
||||||
./build.sh install
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### Open in Xcode (for development)
|
**Features:**
|
||||||
```bash
|
- One-click start/stop from menu bar
|
||||||
open macos-app/AlphaArena.xcodeproj
|
- Real-time P&L updates via WebSocket
|
||||||
```
|
- Native macOS notifications
|
||||||
|
- Network mode toggle (localhost/LAN)
|
||||||
|
|
||||||
### Features
|
**See [docs/MACOS_APP_MANUAL.md](docs/MACOS_APP_MANUAL.md) for full documentation.**
|
||||||
- Native SwiftUI menu bar app
|
|
||||||
- Status icon in menu bar (green=running, gray=stopped)
|
|
||||||
- Start/Stop server with one click
|
|
||||||
- Real-time P&L and position updates via WebSocket
|
|
||||||
- Network mode toggle (localhost vs LAN-accessible)
|
|
||||||
- Rich notifications with action buttons
|
|
||||||
- Open Dashboard, View Logs, Copy URL shortcuts
|
|
||||||
- Preferences window for configuration
|
|
||||||
|
|
||||||
### Menu Bar Controls
|
|
||||||
```
|
|
||||||
┌────────────────────────────────────────┐
|
|
||||||
│ ● Server Running │
|
|
||||||
│ http://127.0.0.1:8000 │
|
|
||||||
├────────────────────────────────────────┤
|
|
||||||
│ P&L: +$127.45 | 5 positions │
|
|
||||||
│ Trading: Active (simulation) │
|
|
||||||
├────────────────────────────────────────┤
|
|
||||||
│ Stop Server ⌘⇧S │
|
|
||||||
│ Open Dashboard ⌘D │
|
|
||||||
│ Copy Server URL ⌘C │
|
|
||||||
│ View Logs ⌘L │
|
|
||||||
├────────────────────────────────────────┤
|
|
||||||
│ Network Mode ▶ │
|
|
||||||
│ ✓ Localhost Only (127.0.0.1) │
|
|
||||||
│ LAN Access (0.0.0.0) │
|
|
||||||
├────────────────────────────────────────┤
|
|
||||||
│ Preferences... ⌘, │
|
|
||||||
│ Quit Alpha Arena ⌘Q │
|
|
||||||
└────────────────────────────────────────┘
|
|
||||||
```
|
|
||||||
|
|
||||||
### Keyboard Shortcuts
|
|
||||||
| Shortcut | Action |
|
|
||||||
|----------|--------|
|
|
||||||
| ⌘S | Start Server |
|
|
||||||
| ⌘⇧S | Stop Server |
|
|
||||||
| ⌘D | Open Dashboard |
|
|
||||||
| ⌘C | Copy Server URL |
|
|
||||||
| ⌘L | View Logs |
|
|
||||||
| ⌘, | Preferences |
|
|
||||||
| ⌘Q | Quit |
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -108,39 +108,55 @@ Alpha Arena is a world-class autonomous trading harness for Polymarket predictio
|
||||||
# 1. Clone and enter directory
|
# 1. Clone and enter directory
|
||||||
cd alpha-arena
|
cd alpha-arena
|
||||||
|
|
||||||
# 2. Create virtual environment
|
# 2. Start (auto-runs setup if needed)
|
||||||
python -m venv venv
|
./alpha start
|
||||||
source venv/bin/activate
|
|
||||||
|
|
||||||
# 3. Install dependencies
|
# 3. Configure credentials
|
||||||
pip install -r requirements.txt
|
nano .env # Add your API keys
|
||||||
|
|
||||||
# 4. Configure credentials
|
# 4. Restart to apply changes
|
||||||
cp .env.example .env
|
./alpha restart
|
||||||
# Edit .env with your API keys
|
|
||||||
|
|
||||||
# 5. Verify setup
|
# 5. Open web UI
|
||||||
python cli.py providers
|
./alpha open
|
||||||
|
|
||||||
# 6. Start simulation
|
|
||||||
python cli.py run --simulation
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
The `./alpha start` command automatically:
|
||||||
|
- Creates the virtual environment (`.venv`)
|
||||||
|
- Installs all dependencies
|
||||||
|
- Creates `.env` from template if missing
|
||||||
|
- Starts the server on port 8000
|
||||||
|
|
||||||
### 2.2 First Live Trade
|
### 2.2 First Live Trade
|
||||||
|
|
||||||
|
1. Open the web dashboard: `./alpha open`
|
||||||
|
2. Navigate to **Trading** page
|
||||||
|
3. Configure your settings
|
||||||
|
4. Start in **simulation mode** first
|
||||||
|
5. When ready, switch to **live mode**
|
||||||
|
|
||||||
|
### 2.3 Advanced CLI (python cli.py)
|
||||||
|
|
||||||
|
For advanced operations, you can use the Python CLI directly:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Ensure .env has WALLET_PRIVATE_KEY and Polymarket credentials
|
# Activate environment first
|
||||||
|
source .venv/bin/activate
|
||||||
|
|
||||||
# Check market status
|
# Start enhanced multi-agent mode
|
||||||
python cli.py markets
|
|
||||||
|
|
||||||
# Start with enhanced multi-agent mode (recommended)
|
|
||||||
python cli.py run-enhanced --dry-run # Preview only
|
python cli.py run-enhanced --dry-run # Preview only
|
||||||
|
|
||||||
# When ready for live trading
|
# When ready for live trading
|
||||||
python cli.py run-enhanced
|
python cli.py run-enhanced
|
||||||
|
|
||||||
|
# Other useful commands
|
||||||
|
python cli.py markets # List markets
|
||||||
|
python cli.py providers # Check LLM status
|
||||||
|
python cli.py backtest # Run backtest
|
||||||
```
|
```
|
||||||
|
|
||||||
|
> **Note:** The `./alpha` script is recommended for daily operations. The `python cli.py` commands provide additional features for advanced users.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 3. Installation & Setup
|
## 3. Installation & Setup
|
||||||
|
|
@ -157,17 +173,17 @@ python cli.py run-enhanced
|
||||||
|
|
||||||
### 3.2 Python Environment
|
### 3.2 Python Environment
|
||||||
|
|
||||||
|
The recommended way is to use `./alpha start` which handles setup automatically.
|
||||||
|
|
||||||
|
For manual setup:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Create isolated environment
|
# Run the setup script (creates .venv)
|
||||||
python -m venv venv
|
./scripts/setup.sh
|
||||||
|
|
||||||
# Activate (macOS/Linux)
|
# Or manually:
|
||||||
source venv/bin/activate
|
python -m venv .venv
|
||||||
|
source .venv/bin/activate
|
||||||
# Activate (Windows)
|
|
||||||
.\venv\Scripts\activate
|
|
||||||
|
|
||||||
# Install dependencies
|
|
||||||
pip install -r requirements.txt
|
pip install -r requirements.txt
|
||||||
|
|
||||||
# Verify installation
|
# Verify installation
|
||||||
|
|
@ -176,6 +192,8 @@ python -c "from src.agents import AgentCoordinator; print('Agents OK')"
|
||||||
python -c "from src.broker import PolymarketBroker; print('Broker OK')"
|
python -c "from src.broker import PolymarketBroker; print('Broker OK')"
|
||||||
```
|
```
|
||||||
|
|
||||||
|
> **Note:** The project uses `.venv` (with dot) as the virtual environment directory.
|
||||||
|
|
||||||
### 3.3 Wallet Setup
|
### 3.3 Wallet Setup
|
||||||
|
|
||||||
1. **Create Polygon Wallet**: Use MetaMask or any Polygon-compatible wallet
|
1. **Create Polygon Wallet**: Use MetaMask or any Polygon-compatible wallet
|
||||||
|
|
@ -363,9 +381,25 @@ AGENT_LOOP_INTERVAL_SECONDS=60
|
||||||
|
|
||||||
## 5. CLI Commands
|
## 5. CLI Commands
|
||||||
|
|
||||||
### 5.1 Command Overview
|
### 5.0 Daily Commands (./alpha)
|
||||||
|
|
||||||
|
For daily operations, use the `./alpha` script:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
|
./alpha start # Start server (auto-setup)
|
||||||
|
./alpha stop # Stop server
|
||||||
|
./alpha status # Check status
|
||||||
|
./alpha logs # Watch logs
|
||||||
|
./alpha open # Open web UI
|
||||||
|
./alpha test # Run tests
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5.1 Advanced CLI (python cli.py)
|
||||||
|
|
||||||
|
For advanced operations, activate the venv and use `python cli.py`:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
source .venv/bin/activate
|
||||||
python cli.py --help
|
python cli.py --help
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -12,6 +12,9 @@ Welcome to Alpha Arena. This guide helps you find the right documentation for yo
|
||||||
### Using the web interface?
|
### Using the web interface?
|
||||||
**[WEB_APP_MANUAL.md](WEB_APP_MANUAL.md)** - Complete web UI guide with screenshots and workflows
|
**[WEB_APP_MANUAL.md](WEB_APP_MANUAL.md)** - Complete web UI guide with screenshots and workflows
|
||||||
|
|
||||||
|
### Using the macOS menu bar app?
|
||||||
|
**[MACOS_APP_MANUAL.md](MACOS_APP_MANUAL.md)** - Native SwiftUI app for menu bar control
|
||||||
|
|
||||||
### Need the full reference?
|
### Need the full reference?
|
||||||
**[USER_MANUAL.md](USER_MANUAL.md)** - CLI commands, multi-agent system, strategies, API reference
|
**[USER_MANUAL.md](USER_MANUAL.md)** - CLI commands, multi-agent system, strategies, API reference
|
||||||
|
|
||||||
|
|
@ -29,6 +32,7 @@ Welcome to Alpha Arena. This guide helps you find the right documentation for yo
|
||||||
|----------|----------|---------|
|
|----------|----------|---------|
|
||||||
| [QUICKSTART.md](../QUICKSTART.md) | Everyone | 5-minute guide, daily commands |
|
| [QUICKSTART.md](../QUICKSTART.md) | Everyone | 5-minute guide, daily commands |
|
||||||
| [WEB_APP_MANUAL.md](WEB_APP_MANUAL.md) | Operators | Web interface, dashboards, controls |
|
| [WEB_APP_MANUAL.md](WEB_APP_MANUAL.md) | Operators | Web interface, dashboards, controls |
|
||||||
|
| [MACOS_APP_MANUAL.md](MACOS_APP_MANUAL.md) | macOS users | Native menu bar app |
|
||||||
| [USER_MANUAL.md](USER_MANUAL.md) | Developers | Full CLI, agents, strategies, API |
|
| [USER_MANUAL.md](USER_MANUAL.md) | Developers | Full CLI, agents, strategies, API |
|
||||||
| [OPERATIONAL_MANUAL.md](OPERATIONAL_MANUAL.md) | DevOps | Deployment, monitoring, security |
|
| [OPERATIONAL_MANUAL.md](OPERATIONAL_MANUAL.md) | DevOps | Deployment, monitoring, security |
|
||||||
| [TESTING.md](TESTING.md) | Developers | Test suite, fixtures, patterns |
|
| [TESTING.md](TESTING.md) | Developers | Test suite, fixtures, patterns |
|
||||||
|
|
@ -40,7 +44,8 @@ Welcome to Alpha Arena. This guide helps you find the right documentation for yo
|
||||||
### Beginner
|
### Beginner
|
||||||
1. Read [../QUICKSTART.md](../QUICKSTART.md) - Get running
|
1. Read [../QUICKSTART.md](../QUICKSTART.md) - Get running
|
||||||
2. Explore [WEB_APP_MANUAL.md](WEB_APP_MANUAL.md) - Use the web UI
|
2. Explore [WEB_APP_MANUAL.md](WEB_APP_MANUAL.md) - Use the web UI
|
||||||
3. Try simulation mode before live trading
|
3. Or try [MACOS_APP_MANUAL.md](MACOS_APP_MANUAL.md) - Native menu bar app
|
||||||
|
4. Try simulation mode before live trading
|
||||||
|
|
||||||
### Intermediate
|
### Intermediate
|
||||||
1. Study [USER_MANUAL.md](USER_MANUAL.md) Sections 6-10 - Agents, strategies, risk
|
1. Study [USER_MANUAL.md](USER_MANUAL.md) Sections 6-10 - Agents, strategies, risk
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue