API_PORT env var now only controls host port mapping in docker-compose.yml.
Container always binds uvicorn to port 8080 internally for consistency
with health checks and documentation.
Update changelog with comprehensive release notes including:
- All features added during alpha testing phase
- Configuration improvements and new documentation
- Bug fixes and stability improvements
- Corrected release date to 2025-10-31
Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Changed merge_jsonl.py to use os.getcwd() instead of os.path.dirname(__file__)
to ensure merged.jsonl is written to the working directory where data files exist,
not to the script's installation directory.
Root cause:
- Dockerfile copies scripts to /app/scripts/ for volume compatibility
- entrypoint.sh runs: cd /app/data && python /app/scripts/merge_jsonl.py
- Old logic used script directory (/app/scripts/), ignoring working directory
- This caused merged.jsonl to be created in /app/scripts/ instead of /app/data/
- Since /app/data/ is volume-mounted, merged file was not visible to host
Solution:
- Scripts now respect current working directory (Unix philosophy)
- Works correctly with volume mounts and script relocation
- Tested in both local and Docker directory structure scenarios
Fixes the issue where merged.jsonl was missing from mounted data volume.
Streamline the data preparation workflow by having get_daily_price.py
automatically invoke merge_jsonl.py after fetching all stock prices.
Changes:
- Modified get_daily_price.py to call merge_jsonl.py automatically
- Updated entrypoint.sh to remove redundant merge_jsonl.py call
- Updated main.sh to remove redundant merge_jsonl.py call
- Fixed import order for linting compliance
Benefits:
- Single command now handles both fetching and merging
- Ensures merged.jsonl is always created after price updates
- Simplifies Docker container startup process
- Prevents missing merged.jsonl errors in production
Add VOLUME_PATH environment variable to customize storage location for
all persistent data (data/, logs/, configs/ subdirectories).
Changes:
- .env.example: Add VOLUME_PATH variable with documentation
- docker-compose.yml: Use ${VOLUME_PATH:-.} for all volume mounts
- docs/DOCKER.md: Document custom volume location feature
Benefits:
- Store data outside project directory (e.g., on separate disk)
- Easier backup/restore (single directory)
- Clean separation of code and data
- Support for absolute or relative paths
Usage:
# In .env file
VOLUME_PATH=/home/user/trading-data
# Results in mounts:
/home/user/trading-data/data:/app/data
/home/user/trading-data/logs:/app/logs
/home/user/trading-data/configs:/app/configs
Defaults to current directory (.) if not set for backward compatibility.
Preserve existing merged.jsonl to avoid data loss and API rate limits.
Only fetch new data if merged.jsonl is missing or empty.
Problem:
- Entrypoint always fetched fresh data from Alpha Vantage on every start
- Overwrote existing mounted data directory
- Caused API rate limit issues and data inconsistencies
- Lost historical data needed for backtesting specific date ranges
Solution:
- Check if merged.jsonl exists and has content before fetching
- Display stock count when using existing data
- Provide manual refresh instructions for when updates are needed
Benefits:
- Faster container startup (no API calls if data exists)
- Avoids Alpha Vantage rate limits (5 calls/min, 500/day)
- Preserves user's existing historical datasets
- Enables reliable backtesting with consistent data
To refresh data: rm data/merged.jsonl && docker-compose restart
Implement automatic detection of custom_config.json for simpler Docker usage.
No environment variables or command-line arguments needed for most users.
Changes:
- entrypoint.sh: Add smart config detection (custom_config.json > CLI arg > default_config.json)
- docker-compose.yml: Add configs volume mount for editing without rebuilds
- docs/DOCKER.md: Update documentation with simplified workflow
- .gitignore: Add custom_config.json to prevent accidental commits
Usage:
cp configs/default_config.json configs/custom_config.json
nano configs/custom_config.json
docker-compose up # Automatically uses custom_config.json
Simplifies user experience by following convention over configuration principle.
Root cause: Python adds script directory (not working directory)
to sys.path. Services in /app/agent_tools/ couldn't import from
/app/tools/ because sys.path[0] was /app/agent_tools.
Solution: Set PYTHONPATH=/app when starting services so /app is
always in the Python import path.
Fixes: ModuleNotFoundError: No module named 'tools' in price.log
Add comment explaining OPENAI_API_BASE can be left empty
to use the default OpenAI endpoint, or set to a custom
proxy URL if needed.
Sets default value to empty instead of placeholder URL.
- Clarify OPENAI_API_BASE can be left empty for default endpoint
- Increase initial wait time from 3s to 5s
- Add health checking for all MCP services (ports 8000-8003)
- Retry up to 10 times with 1s intervals
- Install netcat for port checking
- Display warnings if services aren't ready
Helps diagnose and prevent MCP client initialization errors.
Run MCP service manager from /app instead of /app/agent_tools
to ensure services can import from tools module.
Changes:
- entrypoint.sh: Run start_mcp_services.py from /app directory
- start_mcp_services.py: Use absolute paths for service scripts
- start_mcp_services.py: Set working directory to /app for services
Fixes ModuleNotFoundError: No module named 'tools' in price.log
Replace verbose JSON logging with concise status messages:
- Success: '✓ Fetched SYMBOL'
- Error: '⚠️ SYMBOL: API rate limit or error - [message]'
Prevents logs from being flooded with full JSON responses
for 100+ stock symbols during startup.
Update all GitHub URLs in README from HKUDS/AI-Trader to
Xe138/AI-Trader including:
- Clone URLs (2 locations)
- Support & Community links (Discussions, Issues)
- Badge URLs (stars, forks)
Add validation at startup to check required environment variables:
- OPENAI_API_KEY
- ALPHAADVANTAGE_API_KEY
- JINA_API_KEY
If any are missing, display clear error message with setup
instructions and exit immediately (no restart loop).
Change restart policy from 'unless-stopped' to 'on-failure:3'
to limit restart attempts and prevent endless loops on
configuration errors.
Move get_daily_price.py and merge_jsonl.py to /app/scripts
to prevent volume mount from overlaying the scripts.
Scripts run from /app/data context to output correctly.
Fixes container startup error where scripts were not found
after ./data volume mount replaced container's /app/data.
Add WEB_HTTP_PORT environment variable to configure
the host port for the web interface (port 8888).
Container still uses 8888 internally, but host port
can be customized via .env file.
Internal container ports are now fixed at 8000-8003.
Host ports are configurable via .env variables.
This prevents port conflicts inside the container while
allowing users to map to different host ports if needed.
Pull ghcr.io/xe138/ai-trader:latest by default instead of building.
Add commented build option for local development.
Makes deployment faster for end users.
Replace hardcoded release notes with generic template.
User can complete the release notes before publishing.
Includes TODO markers for summary and changelog content.
Complete guide for creating releases:
- Tag creation and push process
- GitHub Actions automation workflow
- Verification and testing steps
- Troubleshooting common issues
Triggers on release tags (v*) and manual dispatch
Builds and pushes to GitHub Container Registry
Tags with both version and latest
Uses build caching for faster builds
Mounts data and logs volumes for persistence
Injects environment variables from .env file
Exposes all MCP service ports and web dashboard
Auto-restart on failure
Provides comprehensive guidance for working with the AI-Trader codebase including:
- Development commands for setup, data preparation, and running simulations
- Architecture overview of agent system, MCP toolchain, and data flow
- Configuration system with multi-layered priority
- Data formats for positions and price data
- Implementation details and common troubleshooting steps
