diamond-quant 0.1.3
Diamond Quant - MLB MCMC Prediction Tool
Requires Python: >=3.9

# Diamond Quant

MLB MCMC Prediction Tool — Professional baseball game simulation and prediction platform.

## Installation

### Option 1: Using pipx (Recommended for macOS/Linux)

`pipx` installs Python applications in isolated environments, preventing conflicts with system packages.

```bash
# Install pipx (one-time setup)
brew install pipx        # macOS
# OR
pip install --user pipx  # Linux/Windows

# Ensure pipx is in your PATH
pipx ensurepath

# Install diamond-quant
pipx install diamond-quant
```

### Option 2: Using pip (Alternative)

If you prefer using `pip` directly:

```bash
# macOS/Linux (if you get "externally-managed-environment" error)
pip3 install --user diamond-quant

# Or with virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install diamond-quant
```

### Verify Installation

```bash
diamond-quant --help
```

You should see the available commands: `start`, `auth`, and `status`.

## First-Time Setup

### Step 1: Get Your API Key

**You need an API key from your administrator to use Diamond Quant.**

Contact your administrator to receive:
- Your unique API key (a long string of characters)
- Your tier level (MASTER, DIAMOND, GOLD, SILVER, BRONZE, or BASE)

**Note:** Your API key determines your access level and limits. See the [API Key Tiers](#api-key-tiers) section below.

### Step 2: Set Your API Key

```bash
diamond-quant auth
```

You'll be prompted to:
1. Enter your API key (it will be hidden as you type)
2. The tool will validate it against the server
3. If valid, it will be saved securely to `~/.diamond-quant/config.json`

**Example:**
```
API Key Configuration

Enter API key: [hidden input]
Validating API key...
API key saved successfully
```

### Step 3: Start the Application

```bash
diamond-quant start
```

**What happens:**
1. The tool validates your API key and determines your tier
2. Backend API server starts on port 8000
3. Frontend web interface starts on port 3000
4. Your browser should automatically open to `http://localhost:3000`

**Example output:**
```
Starting Diamond Quant...

Found API key, resolving tier...
Tier: DIAMOND
DIAMOND mode: Local SQLite (~/.diamond-quant/data.db)

Starting frontend on port 3000...
Starting backend API on port 8000...
Frontend will connect to: http://localhost:8000

Press Ctrl+C to stop both servers
```

### Step 4: Use the Application

1. Open your browser to `http://localhost:3000`
2. If prompted, enter your API key (it should already be set)
3. Start using Diamond Quant!

**All your data is stored locally** in `~/.diamond-quant/data.db` — no cloud storage required.

## Daily Usage

After the first-time setup, you only need:

```bash
diamond-quant start
```

Your API key is saved, so you won't need to enter it again unless you want to change it.

## Command Reference

### Start Command

```bash
diamond-quant start [OPTIONS]
```

**Options:**
- `--frontend-port PORT` - Port for frontend (default: 3000)
- `--backend-port PORT` - Port for backend API (default: 8000)
- `--skip-auth` - Skip API key authentication (for development only)
- `--api-url URL` - Backend API URL (defaults to http://localhost:{backend-port})
- `--env-file PATH` - Path to .env file

**Examples:**
```bash
# Use custom ports
diamond-quant start --frontend-port 3001 --backend-port 8001

# Skip authentication (development only)
diamond-quant start --skip-auth
```

### Auth Command

```bash
diamond-quant auth
```

Set or update your API key. The tool will:
- Prompt you to enter your API key
- Validate it against the server
- Save it securely if valid

### Status Command

```bash
diamond-quant status
```

Check your current API key configuration and validation status.

## Requirements

- **Python 3.9+** — Check with `python3 --version`
- **Node.js 18+ and npm** — Check with `node --version` and `npm --version`
  - Install from [nodejs.org](https://nodejs.org/) if needed
  - The frontend will automatically build on first run

## Configuration

### Environment Variables (Optional)

For advanced features, you can optionally set these in a `.env` file (in your working directory or `~/.diamond-quant/.env`):

- `ODDS_API_KEY` - Your The Odds API key (for live sportsbook odds)
- `DEEPSEEK_API_KEY` - DeepSeek API key (for AI chat features)
- `GROQ_API_KEY` - Groq API key (alternative AI provider)

**Note:** These are optional. The core application works without them.

### API Key Storage

Your API key is stored in `~/.diamond-quant/config.json` with secure permissions (600 - owner read/write only).

### Local Data Storage

All your simulation results, predictions, and game data are stored locally in `~/.diamond-quant/data.db` (SQLite database). This file is created automatically on first run.

## API Key Tiers

Your API key determines your access level and limits:

| Tier | Sims/Game | Chat/Month | MODELS Tab | Database |
|------|-----------|------------|------------|----------|
| **MASTER** | Unlimited | Unlimited | Yes | Local SQLite |
| **DIAMOND** | 2,000,000 | Unlimited | — | Local SQLite |
| **GOLD** | 500,000 | 1,000 | — | Local SQLite |
| **SILVER** | 100,000 | 500 | — | Local SQLite |
| **BRONZE** | 50,000 | 250 | — | Local SQLite |
| **BASE** | 10,000 | 100 | — | Local SQLite |

**What this means:**
- **Sims/Game**: Maximum number of simulations you can run per game
- **Chat/Month**: Maximum AI chat requests per month (if limited)
- **MODELS Tab**: Access to the advanced models interface
- **Database**: All tiers use local SQLite (your data stays on your machine)

## Troubleshooting

### "externally-managed-environment" Error

If you see this error when installing with `pip`, use `pipx` instead (see Installation Option 1 above) or use `pip3 install --user diamond-quant`.

### "Frontend not built" Error

The frontend will automatically build on first run. Make sure Node.js 18+ and npm are installed:
```bash
node --version  # Should be 18 or higher
npm --version   # Should be installed
```

If Node.js is missing, install it from [nodejs.org](https://nodejs.org/).

### "Cannot connect to API server"

1. Make sure the backend started successfully
2. Check the console output for errors
3. Verify ports 3000 and 8000 are not already in use:
   ```bash
   # Check if ports are in use
   lsof -i :3000
   lsof -i :8000
   ```

### "API key validation failed"

1. **Verify your API key is correct** — Check for typos or extra spaces
2. **Check your internet connection** — Tier validation requires a one-time check against the server
3. **Try again** — The tool will cache your tier locally for offline use after the first successful validation
4. **Contact your administrator** — If the key was working before, it may have been revoked or expired

### Port Already in Use

If ports 3000 or 8000 are already in use, specify different ports:

```bash
diamond-quant start --frontend-port 3001 --backend-port 8001
```

Then access the app at `http://localhost:3001`.

### "Command not found: diamond-quant"

If you installed with `pipx`, make sure `pipx ensurepath` was run and you've restarted your terminal.

If you installed with `pip --user`, the command may be in `~/.local/bin` — add it to your PATH or use:
```bash
~/.local/bin/diamond-quant start
```

## Support

For issues or questions:
- Contact your administrator for API key issues
- Check the console output for detailed error messages
- Refer to this documentation

---

**That's it!** Once installed and configured, just run `diamond-quant start` to begin using Diamond Quant.