shoko/randebu
1
0
Fork 0
Code Issues 6 Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
e41d07486be7becb8078de4b77ad44c708f28d4f
randebu/docs/IMPLEMENTATION_PLAN.md
shokollm 75a6273013 docs: add Phase 1 implementation plan 
- Project overview and target audience
- Architecture diagram (Frontend/Backend/Data layers)
- Tech stack (Svelte, FastAPI, CrewAI, SQLite)
- Database schema with all tables and indexes
- API endpoints (Auth, Bots, Backtest, Simulate, Config)
- CrewAI agent design with roles and tasks
- Backtest engine algorithm
- Simulate engine algorithm
- Frontend pages and components
- Tier gating matrix (Free/Normal/Pro)
- Environment configuration
- Project directory structure
- Deployment steps
- Phase 1 deliverables checklist
- Phase 2 considerations
2026-04-05 22:23:47 +00:00

632 lines
21 KiB
Markdown
Raw Blame History

# AVE Trading Bot - Implementation Plan
> **Project Overview:** An AI-powered trading bot platform where users create and manage trading bots through natural language chat, with backtesting and simulation capabilities.
---
## 1. Concept & Vision
### 1.1 What We're Building
A **prompt-driven AI trading bot platform** that democratizes agentic trading by letting anyone create automated trading strategies through conversation - no coding required.
**Core Promise:** "Create a trading bot by chatting with AI. Test it risk-free. Deploy when you're ready."
### 1.2 Target Audience
- People familiar with trading but not agentic/automated trading
- Want to learn agentic concepts without high barrier to entry
- Have money to trade but limited technical skills
- Age: Productive age (working adults)
- Tech-savvy: Low to moderate - can't run their own agent locally
### 1.3 Core Experience
**Chat-first interface** where users:
1. Describe trading strategies in natural language
2. AI interprets and creates bot configuration
3. User can modify by continuing the conversation
4. Run backtests to validate strategy
5. Run simulations to see real-time signals
6. Deploy to trade live (future phase)
**Multi-bot support:** Up to 3 bots per user, selectable in chat
---
## 2. Architecture Overview
```
┌─────────────────────────────────────────────────────────────┐
│ FRONTEND (Svelte) │
│ - Chat interface (bot creation/modification) │
│ - Bot selector (max 3 bots) │
│ - Backtest results visualization │
│ - Simulation signals dashboard │
└─────────────────────────────────────────────────────────────┘
↕
┌─────────────────────────────────────────────────────────────┐
│ BACKEND (Python FastAPI) │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ │
│ │ Auth │ │ Bot Config │ │ User Management │ │
│ │ (JWT) │ │ (CRUD) │ │ │ │
│ └─────────────┘ └─────────────┘ └─────────────────┘ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ │
│ │ AI Agent │ │ Strategy │ │ Execution │ │
│ │ (CrewAI) │ │ Compiler │ │ Engine │ │
│ └─────────────┘ └─────────────┘ └─────────────────┘ │
│ ┌─────────────┐ ┌─────────────┐ │
│ │ Backtest │ │ Simulate │ │
│ │ Engine │ │ Engine │ │
│ └─────────────┘ └─────────────┘ │
└─────────────────────────────────────────────────────────────┘
↕
┌─────────────────────────────────────────────────────────────┐
│ EXTERNAL SERVICES │
│ ┌─────────────────────┐ ┌────────────────────────────┐ │
│ │ SQLite │ │ AVE Cloud APIs │ │
│ │ - users │ │ - Data API (klines, prices)│ │
│ │ - bots │ │ - Trading API (chain wallet│ │
│ │ - signals │ │ - Proxy wallet (Pro tier) │ │
│ │ - backtests │ └────────────────────────────┘ │
│ │ - simulations │ ┌────────────────────────────┐ │
│ └─────────────────────┘ │ MiniMax API │ │
│ │ (Anthropic format) │ │
│ └────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
---
## 3. Tech Stack
| Layer | Technology | Rationale |
|-------|------------|-----------|
| **Frontend** | Svelte + TypeScript | No Next.js, good DX, lightweight |
| **Backend** | Python FastAPI | Phase 1 - quick to prototype |
| **Backend (Phase 2)** | Bun/TypeScript | Performance, single language |
| **AI Agent** | CrewAI + MiniMax | Multi-agent orchestration |
| **LLM** | MiniMax (Anthropic format) | User has API key |
| **Database** | SQLite | File-based, simple for MVP |
| **Deployment** | Self-hosted (Debian) | User's server, subdomain |
---
## 4. Database Schema
### 4.1 Tables
```sql
-- Users table
CREATE TABLE users (
id TEXT PRIMARY KEY, -- UUID
email TEXT UNIQUE NOT NULL,
password_hash TEXT NOT NULL, -- bcrypt hashed
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
-- Bots table (max 3 per user)
CREATE TABLE bots (
id TEXT PRIMARY KEY, -- UUID
user_id TEXT NOT NULL,
name TEXT NOT NULL,
description TEXT, -- AI-generated description
strategy_config JSON NOT NULL, -- The trading strategy
llm_config JSON NOT NULL, -- Model, temperature, etc.
status TEXT DEFAULT 'draft', -- draft, active, paused
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
FOREIGN KEY (user_id) REFERENCES users(id)
);
-- Bot conversations (chat history)
CREATE TABLE bot_conversations (
id TEXT PRIMARY KEY,
bot_id TEXT NOT NULL,
role TEXT NOT NULL, -- user, assistant, system
content TEXT NOT NULL,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
FOREIGN KEY (bot_id) REFERENCES bots(id)
);
-- Backtest results
CREATE TABLE backtests (
id TEXT PRIMARY KEY,
bot_id TEXT NOT NULL,
started_at TIMESTAMP NOT NULL,
ended_at TIMESTAMP,
status TEXT NOT NULL, -- running, completed, failed
config JSON NOT NULL, -- Backtest parameters
result JSON, -- Final results
FOREIGN KEY (bot_id) REFERENCES bots(id)
);
-- Simulation results
CREATE TABLE simulations (
id TEXT PRIMARY KEY,
bot_id TEXT NOT NULL,
started_at TIMESTAMP NOT NULL,
status TEXT NOT NULL, -- running, stopped
config JSON NOT NULL, -- Simulation parameters
signals JSON, -- Generated signals
FOREIGN KEY (bot_id) REFERENCES bots(id)
);
-- Signals log (for both backtest and simulate)
CREATE TABLE signals (
id TEXT PRIMARY KEY,
bot_id TEXT NOT NULL,
run_id TEXT NOT NULL, -- backtest_id or simulation_id
signal_type TEXT NOT NULL, -- buy, sell, hold
token TEXT NOT NULL,
price REAL NOT NULL,
confidence REAL, -- AI confidence %
reasoning TEXT, -- Why this signal
executed BOOLEAN DEFAULT FALSE, -- If actually executed
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
FOREIGN KEY (bot_id) REFERENCES bots(id)
);
```
### 4.2 Indexes
```sql
CREATE INDEX idx_bots_user_id ON bots(user_id);
CREATE INDEX idx_conversations_bot_id ON bot_conversations(bot_id);
CREATE INDEX idx_backtests_bot_id ON backtests(bot_id);
CREATE INDEX idx_simulations_bot_id ON simulations(bot_id);
CREATE INDEX idx_signals_bot_id ON signals(bot_id);
CREATE INDEX idx_signals_run_id ON signals(run_id);
```
---
## 5. API Endpoints
### 5.1 Auth Routes
| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/auth/register` | Register new user |
| POST | `/api/auth/login` | Login, returns JWT |
| POST | `/api/auth/logout` | Logout (invalidate token) |
| GET | `/api/auth/me` | Get current user |
### 5.2 Bot Routes
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/bots` | List user's bots (max 3) |
| POST | `/api/bots` | Create new bot |
| GET | `/api/bots/{id}` | Get bot details |
| PUT | `/api/bots/{id}` | Update bot |
| DELETE | `/api/bots/{id}` | Delete bot |
| POST | `/api/bots/{id}/chat` | Send message to bot |
| GET | `/api/bots/{id}/history` | Get chat history |
### 5.3 Backtest Routes
| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/bots/{id}/backtest` | Start backtest |
| GET | `/api/bots/{id}/backtest/{run_id}` | Get backtest status/results |
| GET | `/api/bots/{id}/backtests` | List all backtests for bot |
| POST | `/api/bots/{id}/backtest/{run_id}/stop` | Stop running backtest |
### 5.4 Simulation Routes
| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/bots/{id}/simulate` | Start simulation |
| GET | `/api/bots/{id}/simulate/{run_id}` | Get simulation status/signals |
| GET | `/api/bots/{id}/simulations` | List all simulations for bot |
| POST | `/api/bots/{id}/simulate/{run_id}/stop` | Stop simulation |
### 5.5 Config Routes
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/config/chains` | Get supported chains |
| GET | `/api/config/tokens` | Get common tokens |
---
## 6. CrewAI Agent Design
### 6.1 Agent Roles
```python
# For parsing user intent → strategy config
trading_designer = Agent(
role="Trading Strategy Designer",
goal="Design clear, executable trading strategies from natural language",
backstory="Expert in DeFi trading with deep knowledge of indicators, "
"tokenomics, and market patterns. You specialize in translating "
"user requirements into precise trading rules.",
)
# For validating strategy feasibility
strategy_validator = Agent(
role="Strategy Validator",
goal="Ensure strategies are realistic and well-formed",
backstory="Risk management specialist who checks if strategies "
"are implementable and identifies potential issues.",
)
# For generating explanations
strategy_explainer = Agent(
role="Strategy Explainer",
goal="Make complex strategies understandable",
backstory="Education specialist who simplifies trading concepts "
"for beginners without losing accuracy.",
)
```
### 6.2 Default Crew for Bot Chat
```python
trading_crew = Crew(
agents=[trading_designer, strategy_validator, strategy_explainer],
tasks=[understand_intent, validate_strategy, update_config, explain_changes],
process=Process.sequential
)
```
### 6.3 Strategy Config Schema
```json
{
"conditions": [
{
"type": "price_drop",
"token": "PEPE",
"chain": "bsc",
"threshold": 5,
"timeframe": "1h"
}
],
"actions": [
{
"type": "buy",
"amount_percent": 10,
"token": "PEPE"
}
],
"risk_management": {
"stop_loss_percent": 3,
"take_profit_percent": 10
}
}
```
---
## 7. Backtest Engine
### 7.1 Algorithm
```
1. Parse strategy_config → conditions + actions
2. Fetch historical klines from AVE Cloud API
- GET /v2/klines/token/{token-id} or /v2/klines/pair/{pair-id}
- Time range: user-specified
3. For each time point in klines:
a. Check if any condition is met
b. If met → generate signal (buy/sell/hold)
c. Simulate portfolio change
d. Log signal to signals table
4. Calculate metrics:
- Total return %
- Win rate (% correct predictions)
- Max drawdown
- Sharpe ratio
- Number of trades
5. Store results in backtests table
```
### 7.2 Backtest Response
```json
{
"id": "backtest-uuid",
"status": "completed",
"duration_seconds": 45,
"config": {
"token": "PEPE-bsc",
"timeframe": "1h",
"start_date": "2024-01-01",
"end_date": "2024-02-01"
},
"results": {
"total_return": 15.4,
"win_rate": 62.5,
"total_trades": 24,
"buy_signals": 12,
"sell_signals": 12,
"max_drawdown": 8.2,
"sharpe_ratio": 1.45
},
"signals": [...]
}
```
---
## 8. Simulate Engine
### 8.1 Algorithm
```
1. Load bot's strategy_config
2. Start loop (user-initiated):
a. Fetch current prices for relevant tokens
- GET /v2/tokens/price (batch, up to 200)
b. Check if any condition is met
c. If met:
- Generate signal with confidence score
- Log to signals table
- If auto_execute=true → call trading API
- Else → notify user
d. Wait N seconds (configurable, 60s default for free tier)
3. Stop when user stops or max_duration reached
```
### 8.2 User Notice
```
┌─────────────────────────────────────────────────────────────┐
│ ⚠️ Simulation Mode - Free Tier │
│ │
│ Using REST polling (every 60s). For real-time signals, │
│ consider upgrading to Pro tier for WebSocket streams. │
└─────────────────────────────────────────────────────────────┘
```
---
## 9. Frontend Components
### 9.1 Pages
| Route | Purpose |
|-------|---------|
| `/` | Landing or dashboard (if logged in) |
| `/login` | Login form |
| `/register` | Registration form |
| `/dashboard` | Main dashboard (list of bots) |
| `/bot/:id` | Bot chat interface |
| `/bot/:id/backtest` | Backtest results view |
| `/bot/:id/simulate` | Simulation monitor view |
| `/settings` | User settings, API keys |
### 9.2 Key Components
| Component | Purpose |
|-----------|---------|
| `ChatInterface` | Message input, AI responses, chat history |
| `BotCard` | Bot preview card for dashboard |
| `BotSelector` | Dropdown to select which bot to modify (max 3) |
| `StrategyPreview` | Shows parsed strategy config in readable format |
| `SignalChart` | Visual representation of signals over time |
| `BacktestChart` | Line chart of portfolio value over time |
| `ProUpgradeBanner` | Banner shown when feature requires Pro tier |
| `TokenPicker` | Search/select tokens for conditions |
| `ConditionBuilder` | UI for building price/volume conditions |
---
## 10. Tier Gating
| Feature | Free | Normal | Pro |
|---------|------|--------|-----|
| Bot creation (max 3) | ✅ | ✅ | ✅ |
| Chat interface | ✅ | ✅ | ✅ |
| Backtest | ✅ | ✅ | ✅ |
| Simulate (REST polling) | ✅ | ✅ | ✅ |
| Simulate (WebSocket) | ❌ | ❌ | ✅ |
| Chain Wallet trading | ✅ | ✅ | ✅ |
| Proxy Wallet trading | ❌ | ✅ | ✅ |
| Scheduled bot runs | ❌ | ❌ | ✅ |
---
## 11. Environment Configuration
### 11.1 Backend `.env`
```env
# Database
DATABASE_URL=sqlite:///./data/app.db
# Auth
SECRET_KEY=your-super-secret-key-change-in-production
JWT_ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=1440
# MiniMax
MINIMAX_API_KEY=your-minimax-api-key
MINIMAX_MODEL=MiniMax-Text-01
# AVE Cloud
AVE_API_KEY=your-ave-cloud-api-key
AVE_API_PLAN=free
# Server
HOST=0.0.0.0
PORT=8000
DEBUG=false
```
### 11.2 Frontend `.env`
```env
VITE_API_URL=https://bot.yourdomain.com/api
VITE_WS_URL=wss://bot.yourdomain.com/ws
```
---
## 12. Project Structure
```
/home/shoko/repositories/randebu/
├── docs/
│ ├── ave-hackathon-research.md # AVE Cloud research
│ ├── scripts/ # AVE Cloud API scripts
│ │ ├── ave_data_rest.py
│ │ ├── ave_data_wss.py
│ │ ├── ave_trade_rest.py
│ │ └── requirements.txt
│ └── IMPLEMENTATION_PLAN.md # This document
├── src/
│ ├── backend/ # Python FastAPI backend
│ │ ├── app/
│ │ │ ├── api/
│ │ │ │ ├── __init__.py
│ │ │ │ ├── auth.py
│ │ │ │ ├── bots.py
│ │ │ │ ├── backtest.py
│ │ │ │ ├── simulate.py
│ │ │ │ └── config.py
│ │ │ ├── core/
│ │ │ │ ├── __init__.py
│ │ │ │ ├── config.py
│ │ │ │ ├── security.py
│ │ │ │ └── database.py
│ │ │ ├── db/
│ │ │ │ ├── __init__.py
│ │ │ │ ├── models.py
│ │ │ │ └── schemas.py
│ │ │ ├── services/
│ │ │ │ ├── __init__.py
│ │ │ │ ├── ai_agent/
│ │ │ │ │ ├── __init__.py
│ │ │ │ │ ├── crew.py
│ │ │ │ │ └── llm_connector.py
│ │ │ │ ├── backtest/
│ │ │ │ │ ├── __init__.py
│ │ │ │ │ └── engine.py
│ │ │ │ └── simulate/
│ │ │ │ ├── __init__.py
│ │ │ │ └── engine.py
│ │ │ └── main.py
│ │ ├── requirements.txt
│ │ ├── run.py
│ │ └── setup.py
│ └── frontend/ # Svelte frontend
│ ├── src/
│ │ ├── lib/
│ │ │ ├── components/
│ │ │ ├── stores/
│ │ │ └── api/
│ │ ├── routes/
│ │ └── app.html
│ ├── svelte.config.js
│ ├── package.json
│ └── vite.config.ts
└── README.md
```
---
## 13. Deployment
### 13.1 Prerequisites
- Debian server with 8GB RAM, 4 cores
- Python 3.10+
- Node.js 18+
- Nginx
- SSL certificate (Let's Encrypt)
### 13.2 Deployment Steps
```
1. Clone repo to server
git clone https://github.com/your-repo/ave-trading-bot.git
2. Setup Python virtual environment
cd ave-trading-bot/src/backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
3. Setup SQLite database
mkdir -p data
4. Configure Nginx (reverse proxy to localhost:8000)
5. Setup systemd service for auto-restart
6. Start backend service
7. Build frontend
cd ../frontend
npm install
npm run build
8. Serve frontend via Nginx
```
---
## 14. Phase 1 Deliverables
| Deliverable | Status |
|-------------|--------|
| User auth (register, login, logout) | ☐ |
| Bot CRUD (max 3 per user) | ☐ |
| Chat interface with CrewAI | ☐ |
| Strategy parser (NL → config) | ☐ |
| Backtest engine + API | ☐ |
| Backtest results visualization | ☐ |
| Simulate engine + API | ☐ |
| Simulation signals dashboard | ☐ |
| AVE Cloud Data API integration | ☐ |
| AVE Cloud Trading API integration (Chain Wallet) | ☐ |
| Free tier detection + upsell messaging | ☐ |
| SQLite persistence | ☐ |
| Environment config via env vars | ☐ |
| Nginx deployment config | ☐ |
| Systemd service config | ☐ |
| Working deployment on subdomain | ☐ |
---
## 15. Phase 2 Considerations
| Feature | Notes |
|---------|-------|
| Proxy Wallet | Requires Normal+ tier |
| WebSocket streams | Requires Pro tier |
| Scheduled jobs | Need cron/background worker |
| Multiple coordinated bots | Portfolio management |
| Local agent runner | For advanced users |
| Bun/TypeScript backend | Migration from Python |
---
## 16. Open Questions
- [ ] Server SSH access details (to be provided later)
- [ ] Domain/subdomain DNS configuration (to be set up)
- [ ] MiniMax API key (provided via env var)
- [ ] AVE Cloud API key (provided via env var)
---
## 17. Appendix: Supported Conditions (MVP)
| Condition Type | Description | Parameters |
|----------------|-------------|-------------|
| `price_drop` | Token price drops by X% | threshold, timeframe |
| `price_rise` | Token price rises by X% | threshold, timeframe |
| `volume_spike` | Trading volume increases X% | threshold, timeframe |
| `price_level` | Price crosses above/below X | price, direction |
---
*Document Version: 1.0*
*Created: 2026-04-05*
Reference in New Issue View Git Blame Copy Permalink