feat: add resume mode and idempotent behavior to /simulate/trigger endpoint

BREAKING CHANGE: end_date is now required and cannot be null/empty

New Features:
- Resume mode: Set start_date to null to continue from last completed date per model
- Idempotent by default: Skip already-completed dates with replace_existing=false
- Per-model independence: Each model resumes from its own last completed date
- Cold start handling: If no data exists in resume mode, runs only end_date as single day

API Changes:
- start_date: Now optional (null enables resume mode)
- end_date: Now REQUIRED (cannot be null or empty string)
- replace_existing: New optional field (default: false for idempotent behavior)

Implementation:
- Added JobManager.get_last_completed_date_for_model() method
- Added JobManager.get_completed_model_dates() method
- Updated create_job() to support model_day_filter for selective task creation
- Fixed bug with start_date=None in price data checks

Documentation:
- Updated API_REFERENCE.md with complete examples and behavior matrix
- Updated QUICK_START.md with resume mode examples
- Updated docs/user-guide/using-the-api.md
- Added CHANGELOG_NEW_API.md with migration guide
- Updated all integration tests for new schema
- Updated client library examples (Python, TypeScript)

Migration:
- Old: {"start_date": "2025-01-16"}
- New: {"start_date": "2025-01-16", "end_date": "2025-01-16"}
- Resume: {"start_date": null, "end_date": "2025-01-31"}

See CHANGELOG_NEW_API.md for complete details.
This commit is contained in:
2025-11-01 13:34:20 -04:00
parent b9353e34e5
commit 7aa93af6db
7 changed files with 747 additions and 94 deletions

View File

@@ -49,11 +49,12 @@ curl "http://localhost:8080/results?job_id=$JOB_ID" | jq '.'
### Single-Day Simulation
Omit `end_date` to simulate just one day:
Set `start_date` and `end_date` to the same value:
```bash
curl -X POST http://localhost:8080/simulate/trigger \
-d '{"start_date": "2025-01-16", "models": ["gpt-4"]}'
-H "Content-Type: application/json" \
-d '{"start_date": "2025-01-16", "end_date": "2025-01-16", "models": ["gpt-4"]}'
```
### All Enabled Models
@@ -62,9 +63,22 @@ Omit `models` to run all enabled models from config:
```bash
curl -X POST http://localhost:8080/simulate/trigger \
-H "Content-Type: application/json" \
-d '{"start_date": "2025-01-16", "end_date": "2025-01-20"}'
```
### Resume from Last Completed
Use `"start_date": null` to continue from where you left off:
```bash
curl -X POST http://localhost:8080/simulate/trigger \
-H "Content-Type: application/json" \
-d '{"start_date": null, "end_date": "2025-01-31", "models": ["gpt-4"]}'
```
Each model will resume from its own last completed date. If no data exists, runs only `end_date` as a single day.
### Filter Results
```bash