Add design document for layered configuration system that enables
per-deployment model customization while maintaining defaults.
Key features:
- Default config baked into image, user config via volume mount
- Root-level merge with user config taking precedence
- Fail-fast validation at container startup
- Clear error messages on validation failure
Addresses issue where mounted configs would overwrite default config
in image.
- Add FastAPI @app.on_event("startup") handler to display warning
- Previously only appeared when running directly (not via uvicorn)
- Add DEPLOYMENT_MODE and PRESERVE_DEV_DATA to docker-compose.yml
- Update CHANGELOG.md with fix documentation
Fixes issue where dev mode banner wasn't visible in Docker logs
because uvicorn imports app without executing __main__ block.
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.
Add comprehensive warning display when server starts in development mode
to ensure users are aware of simulated AI calls and data handling.
Changes:
- Add log_dev_mode_startup_warning() function in deployment_config.py
- Display warning on main.py startup when DEPLOYMENT_MODE=DEV
- Display warning on API server startup (api/main.py)
- Warning shows AI simulation status and data persistence behavior
- Provides clear instructions for switching to PROD mode
The warning is highly visible and informs users that:
- AI API calls are simulated (no costs incurred)
- Data may be reset between runs (based on PRESERVE_DEV_DATA)
- System is using isolated dev database and paths
Co-Authored-By: Claude <noreply@anthropic.com>
- Add v1.1.0 API Authentication & Security as next priority after v1.0.0
- Include comprehensive security features: API keys, RBAC, rate limiting, audit trail
- Add security warning to v1.0.0 noting lack of authentication
- Resequence all subsequent versions (v1.1-v1.6) to accommodate new feature
- Update version history to reflect new roadmap structure
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Major changes:
- Simplified v0.4.0 to focus on smart date-based simulation API with automatic resume
- Added v1.0.0 milestone for production stability, testing, and validation
- Reorganized post-1.0 features into manageable v1.x releases:
- v1.1.0: Position history & analytics
- v1.2.0: Performance metrics & analytics
- v1.3.0: Data management API
- v1.4.0: Web dashboard UI
- v1.5.0: Advanced configuration & customization
- Moved quantitative modeling to v2.0.0 (major version bump)
Key improvements:
- v0.4.0 now has single /simulate/to-date endpoint with idempotent behavior
- Explicit force_resimulate flag prevents accidental re-simulation
- v1.0.0 includes comprehensive quality gates and production readiness checklist
- Each v1.x release focuses on specific domain for easier implementation
Complete rebrand of project to reflect REST API service architecture:
- Updated all documentation (README, guides, API reference)
- Updated Docker configuration (compose, Dockerfile, images)
- Updated all repository URLs to Xe138/AI-Trader-Server
- Updated all Docker images to ghcr.io/xe138/ai-trader-server
- Added fork acknowledgment crediting HKUDS/AI-Trader
- Updated GitHub Actions workflows and shell scripts
All 4 phases completed with validation checkpoints.
Co-Authored-By: Claude <noreply@anthropic.com>
Update all shell scripts to use the new AI-Trader-Server naming throughout.
Changes:
- main.sh: Update comments and echo statements
- entrypoint.sh: Update startup message
- scripts/validate_docker_build.sh: Update title, container name references,
and docker image tag from ai-trader-test to ai-trader-server-test
- scripts/test_api_endpoints.sh: Update title and docker-compose command
Part of Phase 4: Internal Configuration & Metadata (Task 19)
Update deployment documentation files:
- docker-deployment.md: Update git clone URL, Docker image references
(ghcr.io/xe138/ai-trader to ghcr.io/xe138/ai-trader-server), and
container/service names (ai-trader to ai-trader-server)
- monitoring.md: Update container names in all docker commands
- scaling.md: Update multi-instance service names and Docker image
references
All deployment examples now use ai-trader-server naming.
Part of Phase 3: Developer & Deployment Documentation
Update developer documentation files:
- CONTRIBUTING.md: Update title to AI-Trader-Server
- development-setup.md: Update git clone URL from
github.com/Xe138/AI-Trader to github.com/Xe138/AI-Trader-Server
- testing.md: Update title to reference AI-Trader-Server
Part of Phase 3: Developer & Deployment Documentation
Update all user-guide documentation files:
- configuration.md: Update title and container name references
- using-the-api.md: Update title
- integration-examples.md: Update title, class names
(AsyncAITraderServerClient), container names, DAG names, and log paths
- troubleshooting.md: Update title, container names (ai-trader to
ai-trader-server), GitHub issues URL
All Docker commands and code examples now reference ai-trader-server
container name.
Part of Phase 3: Developer & Deployment Documentation
Added dev database files and dev_agent_data directory to gitignore
to prevent runtime dev data from being committed to the repository.
Patterns added:
- data/jobs_dev.db
- data/*_dev.db
- data/dev_agent_data/
This ensures dev mode runtime data remains local and doesn't pollute
version control.
Added comprehensive implementation plan for development mode feature
and test configuration used during verification.
Files:
- docs/plans/2025-11-01-dev-mode-mock-ai.md: Complete 12-task plan
- configs/test_dev_mode.json: Test configuration for dev mode
These files document the feature implementation process and provide
reference configurations for testing.
Fix critical bug where dev mode was initializing the production database
path instead of the dev database path. The initialize_dev_database() call
now correctly uses get_db_path() to resolve to data/jobs_dev.db.
Impact:
- Before: DEV mode would reset data/jobs.db (production database)
- After: DEV mode correctly resets data/jobs_dev.db (dev database)
Testing:
- Verified database isolation between dev and prod
- Confirmed PRESERVE_DEV_DATA flag works correctly
- Validated dev mode banner and deployment mode detection
Documentation:
- Added comprehensive manual verification results
- Documented all test cases and outcomes
- Recorded fix details for future reference
Task: Task 12 - Manual Verification and Final Testing
Plan: docs/plans/2025-11-01-dev-mode-mock-ai.md
Update project overview and Docker commands to reflect AI-Trader-Server
naming:
- Change project description to emphasize REST API service
- Update Docker image references from ghcr.io/hkuds/ai-trader to
ghcr.io/xe138/ai-trader-server
- Update container names from ai-trader to ai-trader-server
- Update GitHub Actions URL to Xe138/AI-Trader-Server repository
Part of Phase 3: Developer & Deployment Documentation
Update main header comment from 'AI-Trader Environment Configuration' to
'AI-Trader-Server Environment Configuration'
Part of Phase 2: Configuration Files rebrand
Add OCI-compliant metadata labels:
- Title: AI-Trader-Server
- Description: REST API service for autonomous AI trading competitions
- Source: https://github.com/Xe138/AI-Trader-Server
Part of Phase 2: Configuration Files rebrand
Update service name from 'ai-trader' to 'ai-trader-server'
Update container name from 'ai-trader' to 'ai-trader-server'
Update Docker image reference to ghcr.io/xe138/ai-trader-server:latest
Part of Phase 2: Configuration Files rebrand
Add comprehensive development mode documentation to README.md, API_REFERENCE.md, and CLAUDE.md:
README.md:
- New "Development Mode" section after Configuration
- Quick start guide with environment variables
- Explanation of DEV vs PROD mode behavior
- Mock AI behavior and stock rotation details
- Environment variables reference
- Use cases and limitations
API_REFERENCE.md:
- New "Deployment Mode" section after health check
- Response format with deployment_mode fields
- DEV mode behavior explanation
- Health check example with deployment fields
- Use cases for testing and CI/CD
CLAUDE.md:
- New "Development Mode" subsection in Important Implementation Details
- Deployment modes overview
- DEV mode characteristics
- Implementation details with file references
- Testing commands and mock behavior notes
All sections explain:
- DEPLOYMENT_MODE environment variable (PROD/DEV)
- PRESERVE_DEV_DATA flag for dev data persistence
- Mock AI provider with deterministic stock rotation
- Separate dev database and data paths
- Use cases for development and testing
Update API_REFERENCE.md for the AI-Trader-Server rebrand:
- Change title from "AI-Trader API Reference" to "AI-Trader-Server API Reference"
- Update description to reference AI-Trader-Server
- Rename client class examples from AITraderClient to AITraderServerClient
- Update Python and TypeScript/JavaScript code examples
Part of Phase 1 rebrand (Task 3)
Phase 1, Task 1 of rebrand implementation:
- Update title from "AI-Trader: Can AI Beat the Market?" to "AI-Trader-Server: REST API for AI Trading"
- Update "What is AI-Trader?" section to "What is AI-Trader-Server?"
- Update all repository URLs from github.com/Xe138/AI-Trader to github.com/Xe138/AI-Trader-Server
- Update Docker image references from ghcr.io/xe138/ai-trader to ghcr.io/xe138/ai-trader-server
- Update Python client class name from AITraderClient to AITraderServerClient
- Update docker exec container name from ai-trader to ai-trader-server
- Add fork acknowledgment section before License, crediting HKUDS/AI-Trader
- Update back-to-top link to reference new title anchor
All changes emphasize REST API service architecture and maintain consistency with new project naming conventions.
Add comprehensive design document for rebranding project from AI-Trader
to AI-Trader-Server. Includes 4-phase approach with validation
checkpoints, naming conventions, and success criteria.
Co-Authored-By: Claude <noreply@anthropic.com>
Reorganize documentation into user-focused, developer-focused, and deployment-focused sections.
**New structure:**
- Root: README.md (streamlined), QUICK_START.md, API_REFERENCE.md
- docs/user-guide/: configuration, API usage, integrations, troubleshooting
- docs/developer/: contributing, development setup, testing, architecture
- docs/deployment/: Docker deployment, production checklist, monitoring
- docs/reference/: environment variables, MCP tools, data formats
**Changes:**
- Streamline README.md from 831 to 469 lines
- Create QUICK_START.md for 5-minute onboarding
- Create API_REFERENCE.md as single source of truth for API
- Remove 9 outdated specification docs (v0.2.0 API design)
- Remove DOCKER_API.md (content consolidated into new structure)
- Remove docs/plans/ directory with old design documents
- Update CLAUDE.md with documentation structure guide
- Remove orchestration-specific references
**Benefits:**
- Clear entry points for different audiences
- No content duplication
- Better discoverability through logical hierarchy
- All content reflects current v0.3.0 API
Remove config_path from request examples throughout README.md as it is
not a per-request parameter. Config file path is set when initializing
the API server, not with each API call.
Changes:
- Remove config_path from all curl examples
- Remove config_path from TypeScript integration example
- Remove config_path from Python integration example
- Update parameter documentation to clarify config_path is server init only
- Add note that detail level control is not yet implemented in v0.3.0
- Clarify server configuration is set via CONFIG_PATH env var at startup
API Request Parameters (v0.3.0):
- start_date (required)
- end_date (optional, defaults to start_date)
- models (optional, defaults to all enabled models from config)
Server Configuration:
- Set via CONFIG_PATH environment variable or create_app() parameter
- Default: configs/default_config.json
- Contains model definitions and agent settings
Co-Authored-By: Claude <noreply@anthropic.com>
Correct all code examples in Integration Examples and Advanced API
Usage sections to use complete, valid JSON with all required fields.
Changes:
- TypeScript: Fix body type to 'any' and use proper property assignment
- Python: Fix variable overwriting, use unique names for examples
- On-Demand Downloads: Replace '...' with complete JSON examples
- Detail Levels: Add complete curl examples with all required fields
- Concurrent Job Prevention: Show complete API calls with proper JSON
All curl examples now include:
- Content-Type header
- Proper JSON formatting
- All required fields (config_path, start_date, models)
Co-Authored-By: Claude <noreply@anthropic.com>
