goldenChat base source add

ta4j-master/ta4j-examples/README.md

@@ -0,0 +1,100 @@
+# ta4j-examples
+
+`ta4j-examples` is the runnable companion module for `ta4j-core`.
+It is organized as progressive learning tracks so production-minded Java developers can move from first run to robust execution workflows.
+
+## Prerequisites
+
+- JDK 25+
+- Maven 3.9+
+- Build from the repository root where `ta4j-core` and `ta4j-examples` are both available
+
+## Run an example
+
+From the repository root:
+
+```bash
+mvn -pl ta4j-examples exec:java -Dexec.mainClass=ta4jexamples.Quickstart
+```
+
+Replace `ta4jexamples.Quickstart` with any class listed below.
+
+## Verify your run succeeded
+
+Use these quick checks before moving to the next track:
+
+- `ta4jexamples.Quickstart`: prints step-by-step run stages and trade/return metrics
+- `ta4jexamples.backtesting.TradingRecordParityBacktest`: logs execution-model comparison and parity check success
+- `ta4jexamples.backtesting.TradeFillRecordingExample`: logs streamed-vs-grouped fill handling and lot-matching outcomes
+
+If chart windows do not appear, you are likely in a headless environment; switch to chart file output or run on a GUI-enabled machine.
+
+## Learning tracks
+
+### 1) First strategy and metrics
+
+- `ta4jexamples.Quickstart`
+- `ta4jexamples.analysis.StrategyAnalysis`
+
+### 2) Data sourcing and normalization
+
+- `ta4jexamples.backtesting.YahooFinanceBacktest`
+- `ta4jexamples.backtesting.CoinbaseBacktest`
+- `ta4jexamples.datasources.YahooFinanceHttpBarSeriesDataSource`
+- `ta4jexamples.datasources.CoinbaseHttpBarSeriesDataSource`
+
+### 3) Execution semantics and performance
+
+- `ta4jexamples.backtesting.TradingRecordParityBacktest`
+- `ta4jexamples.backtesting.TradeFillRecordingExample`
+- `ta4jexamples.backtesting.SimpleMovingAverageRangeBacktest`
+- `ta4jexamples.backtesting.BacktestPerformanceTuningHarness`
+
+Run a fixed throughput matrix and write `matrix_performance.json`:
+
+```bash
+mvn -pl ta4j-examples -am compile
+mvn -pl ta4j-examples exec:java \
+  -Dexec.mainClass=ta4jexamples.backtesting.BacktestPerformanceTuningHarness \
+  -Dexec.args="--throughputControl --throughputOutputDir .agents/benchmarks/backtest-throughput/current --matrixStrategyCounts 250,500,1000 --matrixBarCounts 500,1000 --matrixMaxBarCountHints 0 --executionMode topK --topK 10 --parallelism 1"
+```
+
+Compare two refs on the same host/spec/dataset:
+
+```bash
+scripts/benchmark-backtest-throughput.sh HEAD^ HEAD
+```
+
+Both refs must include throughput-control support; use `HEAD^` vs `HEAD` after
+the harness and optimization commits are in place. The JSON artifacts include a
+hashed `hostId` plus JVM/OS metadata so reports can be shared without exposing a
+raw machine hostname.
+
+### 4) Live-style workflows
+
+- `ta4jexamples.bots.TradingBotOnMovingBarSeries`
+- `ta4jexamples.backtesting.TradeFillRecordingExample`
+
+### 5) Charting and diagnostics
+
+- `ta4jexamples.indicators.IndicatorsToChart`
+- `ta4jexamples.indicators.CandlestickChart`
+- `ta4jexamples.analysis.CashFlowToChart`
+
+## Suggested progression
+
+1. `ta4jexamples.Quickstart`
+2. `ta4jexamples.backtesting.TradingRecordParityBacktest`
+3. `ta4jexamples.backtesting.TradeFillRecordingExample`
+4. `ta4jexamples.backtesting.SimpleMovingAverageRangeBacktest`
+5. `ta4jexamples.backtesting.YahooFinanceBacktest` or `ta4jexamples.backtesting.CoinbaseBacktest`
+6. `ta4jexamples.bots.TradingBotOnMovingBarSeries`
+
+## Companion guides
+
+- Troubleshooting: https://ta4j.github.io/ta4j-wiki/Troubleshooting-Hub.html
+- Backtesting realism gate: https://ta4j.github.io/ta4j-wiki/Backtesting-Realism-Checklist.html
+- Live operations runbook: https://ta4j.github.io/ta4j-wiki/Live-Trading-Runbook.html
+- Canonical end-to-end path: https://ta4j.github.io/ta4j-wiki/Canonical-User-Journey.html
+- Expected example output signatures: https://ta4j.github.io/ta4j-wiki/Examples-Expected-Outputs.html
+- API migration compatibility map: https://ta4j.github.io/ta4j-wiki/Migration-and-Version-Compatibility.html