Big-Link-Man/docs/stories/story-8.1-job-anchor-text-control.md

Story 8.1: Job-Level Anchor Text Control for T1 and T2+

Story Details

As a user, I want to explicitly specify anchor text terms in my job configuration for both Tier 1 and Tier 2+ links, so that I can include specific terms (like "high volume") that aren't covered by the standard algorithm.

Acceptance Criteria

1. Job JSON Configuration Support

Status: TODO

• Job JSON supports explicit anchor text configuration for both Tier 1 and Tier 2+
• Anchor text can be specified at job-level (applies to all tiers) or tier-level (tier-specific)
• Support for multiple anchor text terms per tier
• Configuration format is intuitive and well-documented

Example Format:

{
  "jobs": [{
    "project_id": 26,
    "anchor_text_config": {
      "mode": "explicit",
      "tier1": ["high volume", "precision machining", "custom manufacturing"],
      "tier2": ["high volume production", "bulk manufacturing", "large scale"]
    },
    "tiers": {
      "tier1": {
        "count": 12,
        "anchor_text_config": {
          "mode": "explicit",
          "terms": ["high volume", "precision"]
        }
      },
      "tier2": {"count": 38}
    }
  }]
}

2. Anchor Text Priority and Usage

Status: TODO

• When explicit anchor text is provided, it should be used instead of algorithm-generated anchor text
• Explicit anchor text takes precedence over algorithm-generated terms
• Anchor text terms are used when injecting links (tiered links, homepage links, money site links, etc.)
• System tries to find explicit terms in content first, then falls back to insertion if not found

3. Backward Compatibility

Status: TODO

• Existing jobs without explicit anchor text continue to work with current algorithm
• Default behavior unchanged when no explicit anchor text is provided
• All existing anchor text modes ("default", "override", "append") continue to work

4. Implementation Details

Status: TODO

• Extend AnchorTextConfig dataclass in src/generation/job_config.py to support tier-specific term lists
• Update _parse_job() and _parse_tier() methods to parse explicit anchor text configuration
• Update _get_anchor_texts_for_tier() in src/interlinking/content_injection.py to prioritize explicit terms
• Add validation to ensure explicit terms are provided when mode is "explicit"
• Update JOB_FIELD_REFERENCE.md with documentation and examples

5. Testing

Status: TODO

• Unit tests for parsing explicit anchor text configuration
• Integration tests verifying explicit anchor text is used in link injection
• Tests for tier-level override of job-level anchor text
• Tests for backward compatibility with existing configurations

Technical Implementation

Changes Required

1. Job Config Parser (src/generation/job_config.py):

   • Extend AnchorTextConfig to support tier1, tier2, etc. fields
   • Update parsing logic to handle tier-specific anchor text lists
   • Add validation for explicit mode requiring term lists

2. Content Injection (src/interlinking/content_injection.py):

   • Update _get_anchor_texts_for_tier() to check for explicit terms first
   • If explicit terms exist, use them; otherwise fall back to current algorithm
   • Support both job-level and tier-level explicit anchor text

3. Documentation:

   • Update JOB_FIELD_REFERENCE.md with new anchor text configuration options
   • Add examples showing explicit anchor text usage

Example Use Cases

1. Wide Variety: User wants to include multiple different terms to a page, which isn't in related_searches or main_keyword variations
2. Brand-Specific Terms: User wants to use specific branded terms that aren't algorithmically generated
3. Industry-Specific Jargon: Terms that are important for SEO but don't appear in standard keyword extraction

Dependencies

• None (standalone feature)

Related Stories

• Story 3.3: Content Interlinking Injection (existing anchor text system)