Add CLI Entrypoint for QuantResearch

README.md

@@ -53,6 +53,26 @@ pip install -e ".[dev]"
 pip install streamlit plotly
 ```
 
+### Quick CLI Usage
+
+After installation, you can use the CLI in two ways:
+
+**Option 1: Direct command (if PATH is configured)**
+```bash
+qrs --help
+python -m quant_research_starter.cli generate-data -o data_sample/sample_prices.csv -s 5 -d 365
+python -m quant_research_starter.cli compute-factors -d data_sample/sample_prices.csv -f momentum -f value -o output/factors.csv
+qrs backtest -d data/sample.csv -s output/factors.csv
+```
+
+**Option 2: Python module (always works)**
+```bash
+python -m quant_research_starter.cli --help
+python -m quant_research_starter.cli generate-data -o data/sample.csv -s 5 -d 365
+python -m quant_research_starter.cli compute-factors -d data/sample.csv -f momentum -f value
+python -m quant_research_starter.cli backtest -d data_sample/sample_prices.csv -s output/factors.csv -o output/backtest_results.json
+```
+
 ### Demo (one-line)
 
 ```bash
@@ -63,13 +83,13 @@ make demo
 
 ```bash
 # generate synthetic sample price series
-qrs generate-data -o data_sample/sample_prices.csv -s 5 -d 365
+python -m quant_research_starter.cli generate-data -o data_sample/sample_prices.csv -s 5 -d 365
 
 # compute example factors
-qrs compute-factors -d data_sample/sample_prices.csv -f momentum -f value -o output/factors.csv
+python -m quant_research_starter.cli compute-factors -d data_sample/sample_prices.csv -f momentum -f value -o output/factors.csv
 
 # run a backtest
-qrs backtest -d data_sample/sample_prices.csv -s output/factors.csv -o output/backtest_results.json
+python -m quant_research_starter.cli backtest -d data_sample/sample_prices.csv -s output/factors.csv -o output/backtest_results.json
 
 # optional: start the Streamlit dashboard
 streamlit run src/quant_research_starter/dashboard/streamlit_app.py
@@ -123,11 +143,13 @@ Supported frequencies:
 
 ## CLI reference
 
-Run `qrs --help` or `qrs <command> --help` for full usage. Main commands include:
+Run `python -m quant_research_starter.cli --help` or `python -m quant_research_starter.cli <command> --help` for full usage. Main commands include:
+
+* `python -m quant_research_starter.cli generate-data` — create synthetic price series or download data from adapters
+* `python -m quant_research_starter.cli compute-factors` — calculate and export factor scores
+* `python -m quant_research_starter.cli backtest` — run the vectorized backtest and export results
 
-* `qrs generate-data` — create synthetic price series or download data from adapters
-* `qrs compute-factors` — calculate and export factor scores
-* `qrs backtest` — run the vectorized backtest and export results
+**Note:** If you have the `qrs` command in your PATH, you can use `qrs` instead of `python -m quant_research_starter.cli`.
 
 ---
 

pyproject.toml

@@ -59,6 +59,12 @@ qrs = "quant_research_starter.cli:cli"
 requires = ["setuptools>=45", "wheel"]
 build-backend = "setuptools.build_meta"
 
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-dir]
+"" = "src"
+
 [tool.black]
 line-length = 88
 target-version = ['py310']

src/quant_research_starter.egg-info/PKG-INFO

@@ -63,6 +63,18 @@ QuantResearchStarter aims to provide a clean, well-documented starting point for
 
 ## Key features
 
+* **Data management** — download market data or generate synthetic price series for experiments.
+* **Factor library** — example implementations of momentum, value, size, and volatility factors.
+* **Vectorized backtesting engine** — supports transaction costs, slippage, and portfolio constraints.
+* **Risk & performance analytics** — returns, drawdowns, Sharpe, turnover, and other risk metrics.
+* **CLI & scripts** — small tools to generate data, compute factors, and run backtests from the terminal.
+* **Production-ready utilities** — type hints, tests, continuous integration, and documentation scaffolding.
+
+---
+
+## Quick start
+
+
 * **Data management** — download market data or generate synthetic price series for experiments.
 * **Factor library** — example implementations of momentum, value, size, and volatility factors.
 * **Vectorized backtesting engine** — supports transaction costs, slippage, portfolio constraints, and configurable rebalancing frequencies (daily, weekly, monthly).

test_cli.py

@@ -0,0 +1,107 @@
+#!/usr/bin/env python3
+"""
+Simple test script for QuantResearch CLI
+This demonstrates all the CLI functionality
+"""
+
+import subprocess
+import sys
+from pathlib import Path
+
+
+def run_command(cmd):
+    """Run a command and print the result"""
+    print(f"\n{'='*60}")
+    print(f"Running: {cmd}")
+    print('='*60)
+    result = subprocess.run(cmd, shell=True, capture_output=True, text=True)
+
+    if result.stdout:
+        print(result.stdout)
+    if result.stderr and result.returncode != 0:
+        print(f"ERROR: {result.stderr}")
+        return False
+
+    return result.returncode == 0
+
+
+def main():
+    """Run all CLI tests"""
+    print("\n🧪 Testing QuantResearch CLI")
+    print("="*60)
+
+    # Define test directories
+    test_data_dir = Path("test_data")
+    test_output_dir = Path("test_output")
+
+    # Create test directories
+    test_data_dir.mkdir(exist_ok=True)
+    test_output_dir.mkdir(exist_ok=True)
+
+    # Test 1: Show help
+    success = run_command("python -m quant_research_starter.cli --help")
+    if not success:
+        print("\n❌ Test 1 FAILED: Help command")
+        sys.exit(1)
+
+    # Test 2: Generate data
+    success = run_command(
+        "python -m quant_research_starter.cli generate-data "
+        "-o test_data/data.csv -s 5 -d 100"
+    )
+    if not success:
+        print("\n❌ Test 2 FAILED: Generate data")
+        sys.exit(1)
+
+    # Test 3: Compute factors
+    success = run_command(
+        "python -m quant_research_starter.cli compute-factors "
+        "-d test_data/data.csv -f momentum -f value -o test_output/factors.csv"
+    )
+    if not success:
+        print("\n❌ Test 3 FAILED: Compute factors")
+        sys.exit(1)
+
+    # Test 4: Run backtest
+    success = run_command(
+        "python -m quant_research_starter.cli backtest "
+        "-d test_data/data.csv -s test_output/factors.csv "
+        "-o test_output/backtest_results.json"
+    )
+    if not success:
+        print("\n❌ Test 4 FAILED: Run backtest")
+        sys.exit(1)
+
+    # Verify output files exist
+    print("\n📁 Checking output files...")
+    files_to_check = [
+        test_data_dir / "data.csv",
+        test_output_dir / "factors.csv",
+        test_output_dir / "backtest_results.json",
+        test_output_dir / "backtest_plot.png"
+    ]
+
+    all_exist = True
+    for file_path in files_to_check:
+        if file_path.exists():
+            print(f"✅ {file_path} exists ({file_path.stat().st_size} bytes)")
+        else:
+            print(f"❌ {file_path} missing!")
+            all_exist = False
+
+    if not all_exist:
+        print("\n❌ Some output files are missing")
+        sys.exit(1)
+
+    # Summary
+    print("\n" + "="*60)
+    print("✅ ALL TESTS PASSED!")
+    print("="*60)
+    print(f"\n📂 Test files created in:")
+    print(f"   - {test_data_dir}/")
+    print(f"   - {test_output_dir}/")
+    print("\n💡 You can view the results and plots in the test_output directory.")
+
+
+if __name__ == "__main__":
+    main()