mirror of
https://github.com/Xe138/AI-Trader.git
synced 2026-04-01 17:17:24 -04:00
224 lines
6.9 KiB
Markdown
224 lines
6.9 KiB
Markdown
# Database Schema
|
|
|
|
SQLite database schema reference.
|
|
|
|
---
|
|
|
|
## Tables
|
|
|
|
### jobs
|
|
Job metadata and overall status.
|
|
|
|
```sql
|
|
CREATE TABLE jobs (
|
|
job_id TEXT PRIMARY KEY,
|
|
config_path TEXT NOT NULL,
|
|
status TEXT CHECK(status IN ('pending', 'running', 'completed', 'partial', 'failed')),
|
|
date_range TEXT, -- JSON array
|
|
models TEXT, -- JSON array
|
|
created_at TEXT,
|
|
started_at TEXT,
|
|
completed_at TEXT,
|
|
total_duration_seconds REAL,
|
|
error TEXT
|
|
);
|
|
```
|
|
|
|
### job_details
|
|
Per model-day execution details.
|
|
|
|
```sql
|
|
CREATE TABLE job_details (
|
|
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
|
job_id TEXT,
|
|
model_signature TEXT,
|
|
trading_date TEXT,
|
|
status TEXT CHECK(status IN ('pending', 'running', 'completed', 'failed')),
|
|
start_time TEXT,
|
|
end_time TEXT,
|
|
duration_seconds REAL,
|
|
error TEXT,
|
|
FOREIGN KEY (job_id) REFERENCES jobs(job_id) ON DELETE CASCADE
|
|
);
|
|
```
|
|
|
|
### trading_days
|
|
|
|
Core table for each model-day execution with daily P&L metrics.
|
|
|
|
```sql
|
|
CREATE TABLE trading_days (
|
|
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
|
job_id TEXT NOT NULL,
|
|
model TEXT NOT NULL,
|
|
date TEXT NOT NULL,
|
|
|
|
-- Starting position (cash only, holdings from previous day)
|
|
starting_cash REAL NOT NULL,
|
|
starting_portfolio_value REAL NOT NULL,
|
|
|
|
-- Daily performance metrics
|
|
daily_profit REAL NOT NULL,
|
|
daily_return_pct REAL NOT NULL,
|
|
|
|
-- Ending state (cash only, holdings in separate table)
|
|
ending_cash REAL NOT NULL,
|
|
ending_portfolio_value REAL NOT NULL,
|
|
|
|
-- Reasoning
|
|
reasoning_summary TEXT,
|
|
reasoning_full TEXT,
|
|
|
|
-- Metadata
|
|
total_actions INTEGER DEFAULT 0,
|
|
session_duration_seconds REAL,
|
|
days_since_last_trading INTEGER DEFAULT 1,
|
|
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
|
completed_at TIMESTAMP,
|
|
|
|
UNIQUE(job_id, model, date),
|
|
FOREIGN KEY (job_id) REFERENCES jobs(job_id)
|
|
);
|
|
|
|
CREATE INDEX idx_trading_days_lookup ON trading_days(job_id, model, date);
|
|
```
|
|
|
|
**Column Descriptions:**
|
|
|
|
| Column | Type | Description |
|
|
|--------|------|-------------|
|
|
| id | INTEGER | Primary key, auto-incremented |
|
|
| job_id | TEXT | Foreign key to jobs table |
|
|
| model | TEXT | Model signature/identifier |
|
|
| date | TEXT | Trading date (YYYY-MM-DD) |
|
|
| starting_cash | REAL | Cash balance at start of day |
|
|
| starting_portfolio_value | REAL | Total portfolio value at start (includes holdings valued at current prices) |
|
|
| daily_profit | REAL | Dollar P&L from previous close (portfolio appreciation/depreciation) |
|
|
| daily_return_pct | REAL | Percentage return from previous close |
|
|
| ending_cash | REAL | Cash balance at end of day |
|
|
| ending_portfolio_value | REAL | Total portfolio value at end |
|
|
| reasoning_summary | TEXT | AI-generated 2-3 sentence summary of trading strategy |
|
|
| reasoning_full | TEXT | JSON array of complete conversation log |
|
|
| total_actions | INTEGER | Number of trades executed during the day |
|
|
| session_duration_seconds | REAL | AI session duration in seconds |
|
|
| days_since_last_trading | INTEGER | Days since previous trading day (1=normal, 3=weekend, 0=first day) |
|
|
| created_at | TIMESTAMP | Record creation timestamp |
|
|
| completed_at | TIMESTAMP | Session completion timestamp |
|
|
|
|
**Important Notes:**
|
|
|
|
- **Day-centric structure:** Each row represents one complete trading day for one model
|
|
- **First trading day:** `daily_profit = 0`, `daily_return_pct = 0`, `days_since_last_trading = 0`
|
|
- **Subsequent days:** Daily P&L calculated by valuing previous day's holdings at current prices
|
|
- **Weekend gaps:** System handles multi-day gaps automatically (e.g., Monday following Friday shows `days_since_last_trading = 3`)
|
|
- **Starting holdings:** Derived from previous day's ending holdings (not stored in this table, see `holdings` table)
|
|
- **Unique constraint:** One record per (job_id, model, date) combination
|
|
|
|
**Daily P&L Calculation:**
|
|
|
|
Daily profit accurately reflects portfolio appreciation from price movements:
|
|
|
|
1. Get previous day's ending holdings and cash
|
|
2. Value those holdings at current day's opening prices
|
|
3. `daily_profit = current_value - previous_value`
|
|
4. `daily_return_pct = (daily_profit / previous_value) * 100`
|
|
|
|
This ensures buying/selling stocks doesn't affect P&L - only price changes do.
|
|
|
|
---
|
|
|
|
### holdings
|
|
|
|
Portfolio holdings snapshots (ending positions only).
|
|
|
|
```sql
|
|
CREATE TABLE holdings (
|
|
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
|
trading_day_id INTEGER NOT NULL,
|
|
symbol TEXT NOT NULL,
|
|
quantity INTEGER NOT NULL,
|
|
|
|
FOREIGN KEY (trading_day_id) REFERENCES trading_days(id) ON DELETE CASCADE,
|
|
UNIQUE(trading_day_id, symbol)
|
|
);
|
|
|
|
CREATE INDEX idx_holdings_day ON holdings(trading_day_id);
|
|
```
|
|
|
|
**Column Descriptions:**
|
|
|
|
| Column | Type | Description |
|
|
|--------|------|-------------|
|
|
| id | INTEGER | Primary key, auto-incremented |
|
|
| trading_day_id | INTEGER | Foreign key to trading_days table |
|
|
| symbol | TEXT | Stock symbol |
|
|
| quantity | INTEGER | Number of shares held at end of day |
|
|
|
|
**Important Notes:**
|
|
|
|
- **Ending positions only:** This table stores only the final holdings at end of day
|
|
- **Starting positions:** Derived by querying holdings for previous day's trading_day_id
|
|
- **Cascade deletion:** Holdings are automatically deleted when parent trading_day is deleted
|
|
- **Unique constraint:** One row per (trading_day_id, symbol) combination
|
|
- **No cash:** Cash is stored directly in trading_days table (`ending_cash`)
|
|
|
|
---
|
|
|
|
### actions
|
|
|
|
Trade execution ledger.
|
|
|
|
```sql
|
|
CREATE TABLE actions (
|
|
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
|
trading_day_id INTEGER NOT NULL,
|
|
|
|
action_type TEXT NOT NULL,
|
|
symbol TEXT,
|
|
quantity INTEGER,
|
|
price REAL,
|
|
|
|
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
|
|
|
FOREIGN KEY (trading_day_id) REFERENCES trading_days(id) ON DELETE CASCADE
|
|
);
|
|
|
|
CREATE INDEX idx_actions_day ON actions(trading_day_id);
|
|
```
|
|
|
|
**Column Descriptions:**
|
|
|
|
| Column | Type | Description |
|
|
|--------|------|-------------|
|
|
| id | INTEGER | Primary key, auto-incremented |
|
|
| trading_day_id | INTEGER | Foreign key to trading_days table |
|
|
| action_type | TEXT | Trade type: 'buy', 'sell', or 'no_trade' |
|
|
| symbol | TEXT | Stock symbol (NULL for no_trade) |
|
|
| quantity | INTEGER | Number of shares traded (NULL for no_trade) |
|
|
| price | REAL | Execution price per share (NULL for no_trade) |
|
|
| created_at | TIMESTAMP | Timestamp of trade execution |
|
|
|
|
**Important Notes:**
|
|
|
|
- **Trade ledger:** Sequential log of all trades executed during a trading day
|
|
- **No_trade actions:** Recorded when agent decides not to trade
|
|
- **Cascade deletion:** Actions are automatically deleted when parent trading_day is deleted
|
|
- **Execution order:** Use `created_at` to determine trade execution sequence
|
|
- **Price snapshot:** Records actual execution price at time of trade
|
|
|
|
### price_data
|
|
Cached historical price data.
|
|
|
|
### price_coverage
|
|
Data availability tracking per symbol.
|
|
|
|
### reasoning_logs
|
|
AI decision reasoning (when enabled).
|
|
|
|
### tool_usage
|
|
MCP tool usage statistics.
|
|
|
|
---
|
|
|
|
See `api/database.py` for complete schema definitions.
|