Add CLI Entrypoint for QuantResearch #18

adityacosmos24 · 2025-10-27T19:07:00Z

📋 Summary

This PR implements a CLI entrypoint for the QuantResearch package, allowing users to install the package with pip install . and run CLI commands via python -m quant_research_starter.cli or the qrs command.

🎯 Issue Addressed

Resolves the feature request to add setuptools/poetry entrypoint so users can pip install . and run quant-starter or similar CLI command.

Labels: packaging, enhancement, easy

🔧 Changes Made

1. Package Configuration (`pyproject.toml`)

✅ Fixed package structure configuration in root pyproject.toml
✅ Added [tool.setuptools.packages.find] to properly locate packages in src/ layout
✅ Added [tool.setuptools.package-dir] to map the root package properly
✅ CLI entrypoint already configured as qrs = "quant_research_starter.cli:cli"

2. Documentation Updates (`README.md`)

✅ Added "Quick CLI Usage" section with two installation methods
✅ Updated step-by-step demo with correct CLI commands
✅ Updated CLI reference section with proper usage examples
✅ Added note about PATH configuration for the qrs command

3. Testing Infrastructure

✅ Created test_cli.py automated test script
✅ Verified all CLI commands work end-to-end

📦 Installation

After merging this PR, users can:

# Clone and install
git clone <repo-url>
cd QuantResearch_Opcode
pip install -e .

# Or just install
pip install -e .

🚀 Usage

Option 1: Python Module (Recommended - Always Works)

# Show help
python -m quant_research_starter.cli --help

# Generate synthetic data
python -m quant_research_starter.cli generate-data -o data.csv -s 5 -d 100

# Compute factors
python -m quant_research_starter.cli compute-factors -d data.csv -f momentum -f value -o factors.csv

# Run backtest
python -m quant_research_starter.cli backtest -d data.csv -s factors.csv -o results.json

Option 2: Direct Command (If PATH is Configured)

qrs --help
qrs generate-data -o data.csv -s 5 -d 100
qrs compute-factors -d data.csv -f momentum -f value -o factors.csv
qrs backtest -d data.csv -s factors.csv -o results.json

🧪 Testing Instructions

Automated Testing

Run the comprehensive test script:

python test_cli.py

This will:

✅ Test CLI help command
✅ Generate synthetic data (5 symbols, 100 days)
✅ Compute momentum and value factors
✅ Run a complete backtest
✅ Verify all output files are created
✅ Show a summary of results

Manual Testing

Test each command individually:

1. Test help commands:

python -m quant_research_starter.cli --help
python -m quant_research_starter.cli generate-data --help
python -m quant_research_starter.cli compute-factors --help
python -m quant_research_starter.cli backtest --help

2. Test data generation:

python -m quant_research_starter.cli generate-data -o test_data.csv -s 10 -d 365
# Verify: test_data.csv should contain 10 symbols with 365 days of data

3. Test factor computation:

python -m quant_research_starter.cli compute-factors \
  -d test_data.csv \
  -f momentum -f value -f size -f volatility \
  -o test_factors.csv
# Verify: test_factors.csv should contain factor scores

4. Test backtest:

python -m quant_research_starter.cli backtest \
  -d test_data.csv \
  -s test_factors.csv \
  -o test_results.json
# Verify: test_results.json and backtest_plot.png should be created

Expected Output

When running the backtest, you should see:

Running backtest...
Backtest completed!
Final portfolio value: $943,186.41
Total return: -5.68%
Sharpe ratio: -0.97
Results saved -> test_results.json
Plot saved -> backtest_plot.png

Verification Checklist

pip install -e . completes without errors
python -m quant_research_starter.cli --help shows the help menu
generate-data command creates a CSV file
compute-factors command creates a CSV with factor scores
backtest command creates JSON results and PNG plot
All output files have non-zero size
Backtest results contain valid metrics (returns, Sharpe ratio, etc.)

📊 Example Workflow

Complete end-to-end workflow:

# 1. Install package
cd QuantResearch_Opcode
pip install -e .

# 2. Generate sample data
python -m quant_research_starter.cli generate-data -o sample_data.csv -s 10 -d 365

# 3. Compute factors
python -m quant_research_starter.cli compute-factors \
  -d sample_data.csv \
  -f momentum -f value \
  -o factors.csv

# 4. Run backtest
python -m quant_research_starter.cli backtest \
  -d sample_data.csv \
  -s factors.csv \
  -o backtest_results.json

# 5. View results
# - Open backtest_results.json to see metrics
# - Open backtest_plot.png to see portfolio performance

🐛 Known Issues / Notes

PATH Warning: On Windows, you may see a warning about the scripts directory not being in PATH. The python -m method works regardless.
First Run: The first CLI command may take a moment as matplotlib builds its font cache.
Negative Returns: The example backtest shows negative returns - this is expected with synthetic data and basic strategies.

📝 Files Changed

pyproject.toml - Fixed package configuration
README.md - Updated usage documentation
test_cli.py - New automated test script
src/pyproject.toml - Removed (duplicate file)

✨ Benefits

Better Developer Experience: Users can now install and run the CLI in one command
Standard Python Packaging: Follows modern Python packaging best practices
Flexible Usage: Two ways to run commands (module or direct)
Well Documented: Clear instructions for installation and usage
Tested: Comprehensive automated and manual tests

🔍 Screenshots

Add screenshots of the CLI in action if desired

📚 Related Documentation

README.md - Updated with CLI usage instructions
test_cli.py - Automated test suite
Original issue description

✅ Checklist

👥 Reviewers

Please pay special attention to:

Package configuration in pyproject.toml
CLI usage examples in README
Test script comprehensiveness

issue resloved #13

Ready for Review 🚀

…iance operations

Enhanced volatility factor implementations for production use, including improved initialization, handling of edge cases, and consistent DataFrame outputs.

Remove unused import statement for warnings.

…rch_Opcode into aditya

Remove unused import statement for warnings.

…rch_Opcode into aditya

Copilot

Pull Request Overview

This PR implements a CLI entrypoint for the QuantResearch package, enabling users to install with pip install . and run commands via python -m quant_research_starter.cli or the qrs command. The PR fixes package discovery configuration and updates documentation to reflect the new CLI usage patterns.

Key Changes:

Fixed package structure configuration in pyproject.toml to properly locate packages in src/ layout
Updated README.md with comprehensive CLI usage instructions and examples
Added automated test script (test_cli.py) for end-to-end CLI validation

Reviewed Changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
pyproject.toml	Added setuptools configuration for package discovery in src/ layout
README.md	Updated CLI usage examples and instructions throughout documentation
test_cli.py	New automated test script for CLI functionality validation
src/quant_research_starter/factors/volatility.py	Refactored volatility factor implementations with vectorized operations
src/quant_research_starter/examples/benchmark/benchmark_factors.py	New benchmark script for factor performance comparison
src/quant_research_starter.egg-info/SOURCES.txt	Updated package source file listing
src/quant_research_starter.egg-info/PKG-INFO	Updated package metadata and documentation

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2025-10-27T19:35:27Z

src/quant_research_starter/factors/volatility.py

+- Proper `__init__` usage.
+- Min_periods set on rolling operations; trimming of initial rows to avoid
+  ambiguous partial-window values.
+- Guarding divide-by-zero when computing beta (market variance).
+- Consistent handling for single-column (single-asset) DataFrames.
+- Preserves DataFrame output shape/columns and sets self._values.
+- Uses ddof=0 for rolling std/var to match population estimates (consistent &
+  fast).


Corrected capitalization of 'min_periods' to 'Min_periods'.

Copilot · 2025-10-27T19:35:27Z

src/quant_research_starter/factors/volatility.py

        returns = prices.pct_change().dropna()
+        if returns.shape[0] < self.lookback:
+            raise ValueError(
+                f"Need at least {self.lookback} non-NA return rows to compute idio-vol"


[nitpick] Use consistent terminology: 'idio-vol' should be 'idiosyncratic volatility' or 'idio_vol' for clarity.

Suggested change

f"Need at least {self.lookback} non-NA return rows to compute idio-vol"

f"Need at least {self.lookback} non-NA return rows to compute idiosyncratic volatility"

Copilot

Pull Request Overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

README.md

src/quant_research_starter.egg-info/PKG-INFO

…rch_Opcode into aditya

Removed duplicated start section from PKG-INFO

Removed typo errors

notes added

right path updated

adityacosmos24 and others added 13 commits October 27, 2025 00:03

feat: optimize idiosyncratic volatility factor using vectorized covar…

9f99632

…iance operations

feat: Reorder imports in benchmark_factors.py

af12d1a

feat: refactor volatility factors for production readiness

327c549

Enhanced volatility factor implementations for production use, including improved initialization, handling of edge cases, and consistent DataFrame outputs.

remove unused import of warnings module

18fe964

Remove unused import statement for warnings.

feat: fixed errors

a4fecd2

Merge branch 'aditya' of https://github.com/adityacosmos24/QuantResea…

e6456f6

…rch_Opcode into aditya

remove unused import in volatility.py

33626dc

Remove unused import statement for warnings.

errors

e0436fb

Merge branch 'aditya' of https://github.com/adityacosmos24/QuantResea…

485151d

…rch_Opcode into aditya

errors

8c54477

fix: sort imports with Ruff

7dbdd60

format code with black

b70d514

feat: added setuptools poetry entrypoint

83f8e31

ayushkrtiwari requested a review from Copilot October 27, 2025 19:34

Copilot AI reviewed Oct 27, 2025

View reviewed changes

adityacosmos24 added 2 commits October 28, 2025 01:21

chore: update readme with new command syntax and paths

badb979

Merge branch 'main' into aditya

c8c5596

ayushkrtiwari added Semver:minor minor version changes PR:Accept To acknowledge the PR hacktoberfest-accepted Type:Medium junior developers talks labels Oct 27, 2025

ayushkrtiwari requested a review from Copilot October 27, 2025 20:10

Copilot AI reviewed Oct 27, 2025

View reviewed changes

README.md Outdated Show resolved Hide resolved

README.md Outdated Show resolved Hide resolved

src/quant_research_starter.egg-info/PKG-INFO Outdated Show resolved Hide resolved

adityacosmos24 and others added 6 commits October 28, 2025 01:42

chore: updated gitignore

50f717d

Merge branch 'aditya' of https://github.com/adityacosmos24/QuantResea…

cfe2ec9

…rch_Opcode into aditya

docs: duplicates removed

dd8b845

Removed duplicated start section from PKG-INFO

docs: fix typo error

77b56b6

Removed typo errors

docs: added description

e140970

notes added

docs: fixed path issue

2f2bf84

right path updated

ayushkrtiwari merged commit 40bc780 into OPCODE-Open-Spring-Fest:main Oct 27, 2025
7 of 8 checks passed

ayushkrtiwari mentioned this pull request Oct 27, 2025

revert: reverts PR #19

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add CLI Entrypoint for QuantResearch #18

Add CLI Entrypoint for QuantResearch #18

Uh oh!

adityacosmos24 commented Oct 27, 2025 •

edited by ayushkrtiwari

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Oct 27, 2025

Uh oh!

Copilot AI Oct 27, 2025

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	f"Need at least {self.lookback} non-NA return rows to compute idio-vol"
	f"Need at least {self.lookback} non-NA return rows to compute idiosyncratic volatility"

Add CLI Entrypoint for QuantResearch #18

Add CLI Entrypoint for QuantResearch #18

Uh oh!

Conversation

adityacosmos24 commented Oct 27, 2025 • edited by ayushkrtiwari Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📋 Summary

🎯 Issue Addressed

🔧 Changes Made

1. Package Configuration (pyproject.toml)

2. Documentation Updates (README.md)

3. Testing Infrastructure

📦 Installation

🚀 Usage

Option 1: Python Module (Recommended - Always Works)

Option 2: Direct Command (If PATH is Configured)

🧪 Testing Instructions

Automated Testing

Manual Testing

Expected Output

Verification Checklist

📊 Example Workflow

🐛 Known Issues / Notes

📝 Files Changed

✨ Benefits

🔍 Screenshots

📚 Related Documentation

✅ Checklist

👥 Reviewers

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI Oct 27, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 27, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

adityacosmos24 commented Oct 27, 2025 •

edited by ayushkrtiwari

Loading

1. Package Configuration (`pyproject.toml`)

2. Documentation Updates (`README.md`)