# Job File Format

Job files define batch content generation parameters using JSON format.

## Structure

```json
{
  "jobs": [
    {
      "project_id": 1,
      "tiers": {
        "tier1": {
          "count": 5,
          "min_word_count": 2000,
          "max_word_count": 2500,
          "min_h2_tags": 3,
          "max_h2_tags": 5,
          "min_h3_tags": 5,
          "max_h3_tags": 10
        }
      }
    }
  ]
}
```

## Fields

### Job Level
- `project_id` (required): The project ID to generate content for
- `tiers` (required): Dictionary of tier configurations
- `deployment_targets` (optional): Array of site custom_hostnames or site_deployment_ids to cycle through
- `deployment_overflow` (optional): Strategy when batch size exceeds deployment_targets ("round_robin", "random_available", or "none"). Default: "round_robin"

### Tier Level
- `count` (required): Number of articles to generate for this tier
- `min_word_count` (optional): Minimum word count (uses defaults if not specified)
- `max_word_count` (optional): Maximum word count (uses defaults if not specified)
- `min_h2_tags` (optional): Minimum H2 headings (uses defaults if not specified)
- `max_h2_tags` (optional): Maximum H2 headings (uses defaults if not specified)
- `min_h3_tags` (optional): Minimum H3 subheadings total (uses defaults if not specified)
- `max_h3_tags` (optional): Maximum H3 subheadings total (uses defaults if not specified)

## Tier Defaults

If tier parameters are not specified, these defaults are used:

### tier1
- `min_word_count`: 2000
- `max_word_count`: 2500
- `min_h2_tags`: 3
- `max_h2_tags`: 5
- `min_h3_tags`: 5
- `max_h3_tags`: 10

### tier2
- `min_word_count`: 1500
- `max_word_count`: 2000
- `min_h2_tags`: 2
- `max_h2_tags`: 4
- `min_h3_tags`: 3
- `max_h3_tags`: 8

### tier3
- `min_word_count`: 1000
- `max_word_count`: 1500
- `min_h2_tags`: 2
- `max_h2_tags`: 3
- `min_h3_tags`: 2
- `max_h3_tags`: 6

## Examples

### Simple: Single Tier with Defaults
```json
{
  "jobs": [
    {
      "project_id": 1,
      "tiers": {
        "tier1": {
          "count": 5
        }
      }
    }
  ]
}
```

### Custom Word Counts
```json
{
  "jobs": [
    {
      "project_id": 1,
      "tiers": {
        "tier1": {
          "count": 3,
          "min_word_count": 2500,
          "max_word_count": 3000
        }
      }
    }
  ]
}
```

### Multi-Tier
```json
{
  "jobs": [
    {
      "project_id": 1,
      "tiers": {
        "tier1": {
          "count": 5
        },
        "tier2": {
          "count": 10
        },
        "tier3": {
          "count": 15
        }
      }
    }
  ]
}
```

### Multiple Projects
```json
{
  "jobs": [
    {
      "project_id": 1,
      "tiers": {
        "tier1": {
          "count": 5
        }
      }
    },
    {
      "project_id": 2,
      "tiers": {
        "tier1": {
          "count": 3
        },
        "tier2": {
          "count": 8
        }
      }
    }
  ]
}
```

## Usage

Run batch generation with:

```bash
python main.py generate-batch --job-file jobs/example_tier1_batch.json --username youruser --password yourpass
```

### Options
- `--job-file, -j`: Path to job JSON file (required)
- `--username, -u`: Username for authentication
- `--password, -p`: Password for authentication
- `--debug`: Save AI responses to debug_output/
- `--continue-on-error`: Continue processing if article generation fails
- `--model, -m`: AI model to use (default: gpt-4o-mini)

### Deployment Target Assignment (Story 2.5)

Optionally specify which sites/buckets to deploy articles to:

```json
{
  "jobs": [
    {
      "project_id": 1,
      "deployment_targets": [
        "www.domain1.com",
        "www.domain2.com",
        "www.domain3.com"
      ],
      "deployment_overflow": "round_robin",
      "tiers": {
        "tier1": {
          "count": 10
        }
      }
    }
  ]
}
```

This generates 10 articles distributed across 3 sites:
- Articles 0, 3, 6, 9 → domain1.com
- Articles 1, 4, 7 → domain2.com  
- Articles 2, 5, 8 → domain3.com

**Overflow Strategies:**
- `round_robin` (default): Cycle back through specified targets
- `random_available`: Use random sites not in the targets list
- `none`: Error if batch exceeds target count (strict mode)

If `deployment_targets` is omitted, articles receive random templates (no site assignment).

### Debug Mode

When using `--debug`, AI responses are saved to `debug_output/`:
- `title_project{id}_tier{tier}_article{n}_{timestamp}.txt`
- `outline_project{id}_tier{tier}_article{n}_{timestamp}.json`
- `content_project{id}_tier{tier}_article{n}_{timestamp}.html`
- `augmented_project{id}_tier{tier}_article{n}_{timestamp}.html` (if augmented)