Merge branch 'main' of https://github.com/AKKI0511/QuantTradeAI into feat/backtest-model-cli

Author: QuantTradeAI Maintainer

.env.example

@@ -0,0 +1,42 @@
+# QuantTradeAI example environment file
+#
+# Copy to .env and fill in values. Do NOT commit .env.
+
+########################################
+# Data Providers (optional)
+########################################
+# Required ONLY if you use AlphaVantageDataSource
+ALPHAVANTAGE_API_KEY=""
+
+########################################
+# LLM Sentiment (optional)
+########################################
+# Required if sentiment.enabled=true AND provider=openai
+OPENAI_API_KEY=""
+
+# Required if sentiment.enabled=true AND provider=anthropic
+ANTHROPIC_API_KEY=""
+
+# Required if sentiment.enabled=true AND provider=huggingface
+HUGGINGFACE_API_KEY=""
+
+# Ollama typically runs locally and does not require an API key
+# (no env var needed)
+
+########################################
+# Streaming Providers (optional)
+########################################
+# For providers using `auth_method: api_key`, the convention is:
+#   <PROVIDER>_API_KEY and <PROVIDER>_API_SECRET
+
+# Alpaca example (required if using provider name "alpaca")
+ALPACA_API_KEY=""
+ALPACA_API_SECRET=""
+
+# Other providers (uncomment as needed)
+# INTERACTIVE_BROKERS_API_KEY=""
+# INTERACTIVE_BROKERS_API_SECRET=""
+# BINANCE_API_KEY=""
+# BINANCE_API_SECRET=""
+# COINBASE_API_KEY=""
+# COINBASE_API_SECRET=""

AGENTS.md

@@ -37,3 +37,9 @@
 - Centralize knobs in YAML under `config/`; validate changes with `verify_config_loading.py`.
 - Write outputs to `data/`, `models/`, `reports/` (these paths are gitignored by default).
 
+## Evaluation & Splitting (Important)
+- Train/test splits are time-aware:
+  - Prefer `data.test_start` and optional `data.test_end` in `config/model_config.yaml`.
+  - If unset, the last `training.test_size` fraction is used as test chronologically (no shuffle).
+- Hyperparameter tuning uses `TimeSeriesSplit(n_splits=training.cv_folds)` to avoid leakage.
+- Ensure any configured test window falls within `data.start_date`/`data.end_date`.

LLM.md

@@ -68,7 +68,7 @@ make test     # pytest testing
 - **Pydantic** - Configuration validation
 - **joblib** - Model persistence
 
-## API Structure
+## API Structure
 
 ### Data Loading
 ```python
@@ -84,15 +84,19 @@ df_processed = processor.process_data(df)
 df_labeled = processor.generate_labels(df_processed)
 ```
 
-### Model Training
-```python
-from quanttradeai import MomentumClassifier
-
-# Initialize and train
-classifier = MomentumClassifier("config/model_config.yaml")
-X, y = classifier.prepare_data(df_labeled)
-classifier.train(X, y)
-```
+### Model Training
+```python
+from quanttradeai import MomentumClassifier
+
+# Initialize and train
+classifier = MomentumClassifier("config/model_config.yaml")
+X, y = classifier.prepare_data(df_labeled)
+classifier.train(X, y)
+```
+
+### Evaluation & Splitting
+- CLI training performs time‑aware splits using `data.test_start` and optional `data.test_end` in `config/model_config.yaml`. If unset, the last `training.test_size` fraction is used chronologically (no shuffle).
+- Hyperparameter tuning uses `TimeSeriesSplit(n_splits=training.cv_folds)` to prevent look‑ahead bias during CV.
 
 ### Backtesting
 ```python
@@ -338,4 +342,4 @@ For CLI and Python examples see [docs/llm-sentiment.md](docs/llm-sentiment.md).
 
 ---
 
-**Remember**: Always test thoroughly, follow coding standards, and maintain documentation. This codebase is used for financial applications - accuracy and reliability are paramount.
+**Remember**: Always test thoroughly, follow coding standards, and maintain documentation. This codebase is used for financial applications - accuracy and reliability are paramount.