mirror of
https://github.com/Xe138/AI-Trader.git
synced 2026-04-01 17:17:24 -04:00
Bill
e5b83839ad
Added documentation for: - Duplicate simulation prevention in JobManager.create_job() - Cross-job portfolio continuity in position tracking - Updated CLAUDE.md with Duplicate Simulation Prevention section - Updated docs/developer/architecture.md with Position Tracking Across Jobs section
94 lines
2.1 KiB
Markdown
94 lines
2.1 KiB
Markdown
# Architecture
|
|
|
|
System design and component overview.
|
|
|
|
---
|
|
|
|
## Component Diagram
|
|
|
|
See README.md for architecture diagram.
|
|
|
|
---
|
|
|
|
## Key Components
|
|
|
|
### FastAPI Server (`api/main.py`)
|
|
- REST API endpoints
|
|
- Request validation
|
|
- Response formatting
|
|
|
|
### Job Manager (`api/job_manager.py`)
|
|
- Job lifecycle management
|
|
- SQLite operations
|
|
- Concurrency control
|
|
|
|
### Simulation Worker (`api/simulation_worker.py`)
|
|
- Background job execution
|
|
- Date-sequential, model-parallel orchestration
|
|
- Error handling
|
|
|
|
### Model-Day Executor (`api/model_day_executor.py`)
|
|
- Single model-day execution
|
|
- Runtime config isolation
|
|
- Agent invocation
|
|
|
|
### Base Agent (`agent/base_agent/base_agent.py`)
|
|
- Trading session execution
|
|
- MCP tool integration
|
|
- Position management
|
|
|
|
### MCP Services (`agent_tools/`)
|
|
- Math, Search, Trade, Price tools
|
|
- Internal HTTP servers
|
|
- Localhost-only access
|
|
|
|
---
|
|
|
|
## Data Flow
|
|
|
|
1. API receives trigger request
|
|
2. Job Manager validates and creates job
|
|
3. Worker starts background execution
|
|
4. For each date (sequential):
|
|
- For each model (parallel):
|
|
- Executor creates isolated runtime config
|
|
- Agent executes trading session
|
|
- Results stored in database
|
|
5. Job status updated
|
|
6. Results available via API
|
|
|
|
---
|
|
|
|
## Anti-Look-Ahead Controls
|
|
|
|
- `TODAY_DATE` in runtime config limits data access
|
|
- Price queries filter by date
|
|
- Search results filtered by publication date
|
|
|
|
See [CLAUDE.md](../../CLAUDE.md) for implementation details.
|
|
|
|
---
|
|
|
|
## Position Tracking Across Jobs
|
|
|
|
**Design:** Portfolio state is tracked per-model across all jobs, not per-job.
|
|
|
|
**Query Logic:**
|
|
```python
|
|
# Get starting position for current trading day
|
|
SELECT id, ending_cash FROM trading_days
|
|
WHERE model = ? AND date < ? # No job_id filter
|
|
ORDER BY date DESC
|
|
LIMIT 1
|
|
```
|
|
|
|
**Benefits:**
|
|
- Portfolio continuity when creating new jobs with overlapping dates
|
|
- Prevents accidental portfolio resets
|
|
- Enables flexible job scheduling (resume, rerun, backfill)
|
|
|
|
**Example:**
|
|
- Job 1: Runs 2025-10-13 to 2025-10-15 for model-a
|
|
- Job 2: Runs 2025-10-16 to 2025-10-20 for model-a
|
|
- Job 2 starts with Job 1's ending position from 2025-10-15
|