feat: Add database init on startup and documentation
- Add lifespan handler to main.py for automatic DB table creation - Expand .env.example with detailed variable documentation - Add AUDIT_REPORT.md with comprehensive product/technical review - Add STRATEGY_SCHEMA.md as single source of truth for strategy config - Remove redundant init_db.py script (DB init now handled by app startup)
This commit is contained in:
shokollm
279
docs/STRATEGY_SCHEMA.md
Normal file
279
docs/STRATEGY_SCHEMA.md
Normal file
@@ -0,0 +1,279 @@
|
||||
# Strategy Config Schema
|
||||
|
||||
> **Status:** DRAFT - Needs to be normalized with implementation
|
||||
> **Purpose:** Single source of truth for strategy configuration format
|
||||
|
||||
---
|
||||
|
||||
## 1. Overview
|
||||
|
||||
This document defines the structure of the `strategy_config` JSON object that represents a trading bot's strategy. This config is:
|
||||
- Generated by the AI from natural language input
|
||||
- Validated by the backend
|
||||
- Used by backtest and simulation engines
|
||||
- Displayed in the frontend
|
||||
|
||||
---
|
||||
|
||||
## 2. Schema Version
|
||||
|
||||
**Current Version:** 1.0
|
||||
**Status:** Flat structure (NOT nested in `params`)
|
||||
|
||||
> **IMPORTANT:** The current implementation has a mismatch where the LLM outputs a nested `params` structure but the engines expect flat fields. This document defines the **TARGET** schema to normalize all components.
|
||||
|
||||
---
|
||||
|
||||
## 3. Full Schema
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "1.0",
|
||||
"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
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Field Definitions
|
||||
|
||||
### 4.1 Root Fields
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `version` | string | No | Schema version (for future compatibility) |
|
||||
| `conditions` | array | Yes | List of trigger conditions |
|
||||
| `actions` | array | Yes | List of actions to execute when conditions are met |
|
||||
| `risk_management` | object | No | Risk management settings |
|
||||
|
||||
### 4.2 Condition Object
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `type` | string | Yes | Condition type (see supported types below) |
|
||||
| `token` | string | Yes | Token symbol or address (e.g., "PEPE" or "0x123...-bsc") |
|
||||
| `chain` | string | No | Blockchain chain (default: "bsc") |
|
||||
| `threshold` | number | For price_drop/rise/volume_spike | Percentage threshold (e.g., 5 = 5%) |
|
||||
| `price` | number | For price_level | Price level to trigger on |
|
||||
| `direction` | string | For price_level | "above" or "below" |
|
||||
| `timeframe` | string | No | Time window for calculation (e.g., "1h", "15m") |
|
||||
|
||||
#### Supported Condition Types
|
||||
|
||||
| Type | Description | Required Fields |
|
||||
|------|-------------|-----------------|
|
||||
| `price_drop` | Triggers when token price drops by threshold % | token, threshold |
|
||||
| `price_rise` | Triggers when token price rises by threshold % | token, threshold |
|
||||
| `volume_spike` | Triggers when trading volume increases by threshold % | token, threshold |
|
||||
| `price_level` | Triggers when price crosses a specific level | token, price, direction |
|
||||
|
||||
### 4.3 Action Object
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `type` | string | Yes | Action type (buy, sell, hold, notify) |
|
||||
| `amount_percent` | number | For buy/sell | Percentage of portfolio to trade |
|
||||
| `token` | string | No | Token to trade (defaults to condition token) |
|
||||
|
||||
#### Supported Action Types
|
||||
|
||||
| Type | Description | Required Fields |
|
||||
|------|-------------|-----------------|
|
||||
| `buy` | Purchase tokens | amount_percent |
|
||||
| `sell` | Sell tokens | amount_percent |
|
||||
| `hold` | Do nothing (log only) | - |
|
||||
| `notify` | Send notification to user | - |
|
||||
|
||||
### 4.4 Risk Management Object
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `stop_loss_percent` | number | No | Exit trade if loss exceeds this % |
|
||||
| `take_profit_percent` | number | No | Exit trade if profit reaches this % |
|
||||
|
||||
---
|
||||
|
||||
## 5. Examples
|
||||
|
||||
### 5.1 Simple Buy on Price Drop
|
||||
|
||||
> "Buy PEPE when it drops 5% in 1 hour"
|
||||
|
||||
```json
|
||||
{
|
||||
"conditions": [
|
||||
{
|
||||
"type": "price_drop",
|
||||
"token": "PEPE",
|
||||
"chain": "bsc",
|
||||
"threshold": 5,
|
||||
"timeframe": "1h"
|
||||
}
|
||||
],
|
||||
"actions": [
|
||||
{
|
||||
"type": "buy",
|
||||
"amount_percent": 10
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 5.2 Buy on Price Rise with Stop Loss
|
||||
|
||||
> "Buy when PEPE rises 10%, but stop loss at 3%"
|
||||
|
||||
```json
|
||||
{
|
||||
"conditions": [
|
||||
{
|
||||
"type": "price_rise",
|
||||
"token": "PEPE",
|
||||
"threshold": 10,
|
||||
"timeframe": "4h"
|
||||
}
|
||||
],
|
||||
"actions": [
|
||||
{
|
||||
"type": "buy",
|
||||
"amount_percent": 20
|
||||
}
|
||||
],
|
||||
"risk_management": {
|
||||
"stop_loss_percent": 3
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 5.3 Sell on Price Level
|
||||
|
||||
> "Sell when PEPE reaches $0.0001"
|
||||
|
||||
```json
|
||||
{
|
||||
"conditions": [
|
||||
{
|
||||
"type": "price_level",
|
||||
"token": "PEPE",
|
||||
"price": 0.0001,
|
||||
"direction": "above"
|
||||
}
|
||||
],
|
||||
"actions": [
|
||||
{
|
||||
"type": "sell",
|
||||
"amount_percent": 100
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 5.4 Volume Spike Alert
|
||||
|
||||
> "Notify me when PEPE volume spikes 50%"
|
||||
|
||||
```json
|
||||
{
|
||||
"conditions": [
|
||||
{
|
||||
"type": "volume_spike",
|
||||
"token": "PEPE",
|
||||
"threshold": 50,
|
||||
"timeframe": "1h"
|
||||
}
|
||||
],
|
||||
"actions": [
|
||||
{
|
||||
"type": "notify"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Validation Rules
|
||||
|
||||
### 6.1 Conditions
|
||||
|
||||
- At least one condition is required
|
||||
- Each condition must have a valid `type`
|
||||
- Token must be specified
|
||||
- Threshold must be positive number (for applicable types)
|
||||
- Price level must be specified for `price_level` type
|
||||
- Direction must be "above" or "below" for `price_level` type
|
||||
|
||||
### 6.2 Actions
|
||||
|
||||
- At least one action is required
|
||||
- Each action must have a valid `type`
|
||||
- `amount_percent` must be between 0 and 100
|
||||
|
||||
### 6.3 Risk Management
|
||||
|
||||
- `stop_loss_percent` must be positive
|
||||
- `take_profit_percent` must be positive
|
||||
|
||||
---
|
||||
|
||||
## 7. Implementation Status
|
||||
|
||||
### Components Using This Schema
|
||||
|
||||
| Component | Status | Notes |
|
||||
|-----------|--------|-------|
|
||||
| Backend Validator (crew.py) | ❌ Mismatch | Uses nested `params` structure |
|
||||
| Backtest Engine | ❌ Mismatch | Uses flat structure (correct) |
|
||||
| Simulate Engine | ❌ Mismatch | Uses flat structure (correct) |
|
||||
| Frontend Types | ✅ Match | Uses flat structure |
|
||||
| Frontend StrategyPreview | ✅ Match | Uses flat structure |
|
||||
|
||||
### Normalization Required
|
||||
|
||||
The LLM output parser should be updated to output flat structure (not nested in `params`) to match what the engines and frontend expect.
|
||||
|
||||
---
|
||||
|
||||
## 8. Future Extensions
|
||||
|
||||
### Potential Condition Types (Phase 2+)
|
||||
|
||||
| Type | Description |
|
||||
|------|-------------|
|
||||
| `rsi_oversold` | RSI indicator below threshold |
|
||||
| `rsi_overbought` | RSI indicator above threshold |
|
||||
| `ma_crossover` | Moving average crossover |
|
||||
| `bollinger_breakout` | Bollinger Band breakout |
|
||||
| `news_sentiment` | Based on news sentiment analysis |
|
||||
|
||||
### Potential Action Types (Phase 2+)
|
||||
|
||||
| Type | Description |
|
||||
|------|-------------|
|
||||
| `dca_buy` | Dollar cost averaging buy |
|
||||
| `trailing_stop` | Trailing stop loss |
|
||||
| `smart_rebalance` | Portfolio rebalancing |
|
||||
|
||||
---
|
||||
|
||||
*Document Version: 1.0*
|
||||
*Last Updated: 2026-04-09*
|
||||
Reference in New Issue
Block a user