# GEM - Global Equities Momentum

A professional dual momentum investing strategy tool built with Python, featuring robust configuration management, CLI interface, and comprehensive financial analysis capabilities.

This implementation is based on the Dual Momentum / Global Equities Momentum strategy described by Gary Antonacci. This repository is not affiliated with the author.

> **🤖 AI-Generated Code**: This entire project was created using AI-assisted coding (vibe coding) to demonstrate modern Python development practices and financial analysis capabilities. The code structure, architecture, and implementation were generated by AI with human guidance.

## 🚀 Basic Usage

### Prerequisites

- **Python 3.13+** (required for modern type hints and features)
- **pip** or **uv** package manager (uv recommended for faster dependency resolution)

### Ticker Compatibility

**⚠️ Important**: This tool only works with ticker symbols that are compatible with Yahoo Finance.

You can verify ticker compatibility by checking if the symbol exists on [Yahoo Finance](https://finance.yahoo.com/).

### Installation

```bash
# Clone the repository
git clone https://github.com/karta9821/global-equities-momentum.git
cd global-equities-momentum

# Install with uv (recommended)
uv sync
uv pip install -e .

# Or install with pip
pip install -e .
```

### Quick Commands

```bash
# Run analysis with default settings
gem

# Analyze specific symbols
gem --mode analyze --symbols EIMI.L IWDA.L CNDX.L

# Validate symbols
gem --mode validate --symbols EIMI.L IWDA.L

# Show help
gem --help
```

## 🌐 View Current Analysis

You can view the latest GEM analysis results directly in your browser without installing anything:

**[📊 View Current GEM Analysis](https://karta9821.github.io/global-equities-momentum/)**

The GitHub Pages site is automatically updated with the latest analysis results, showing current momentum rankings and charts for global stock markets.

## 🍴 Fork and Run Locally

I recommend forking this repository to run it on your own GitHub Actions and customize it for your needs.

### 1. Fork the Repository

1. Go to [https://github.com/karta9821/global-equities-momentum](https://github.com/karta9821/global-equities-momentum)
2. Click the "Fork" button in the top-right corner
3. Clone your forked repository:

   ```bash
   git clone https://github.com/YOUR_USERNAME/global-equities-momentum.git
   cd gem
   ```

### 2. Set Up GitHub Actions

The project includes GitHub Actions workflows for automated testing and deployment. After forking:

1. **Enable GitHub Actions** in your forked repository settings
2. **Set up environment variables** if needed in Settings → Secrets and variables → Actions
3. **Push changes** to trigger the workflows

### 3. Run Locally

```bash
# Install dependencies
uv sync

# Install in development mode
uv pip install -e .

# Test the installation
gem --help
```

## ⚠️ Important Disclaimers

### Investment Disclaimer

**This tool is for educational and research purposes only.** Always do your own research and consider consulting with a financial advisor before making investment decisions. Past performance does not guarantee future results.

### AI-Generated Code Disclaimer

**This project was entirely created using AI-assisted coding.** While the code follows best practices and has been tested, it serves as a demonstration of AI-assisted development capabilities. Users should review and validate the code according to their specific needs and requirements.

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

**Built with ❤️ using AI-assisted development practices**
