How I Use GPT to Automate Contextual Internal Linking (Without Making It Spammy)

"""
================================================================================
🧩 Script: Contextual Link Opportunity Finder for WordPress Blog Content
--------------------------------------------------------------------------------

🎯 PURPOSE:
This Python script is designed to automate the identification of *contextually relevant*
internal linking opportunities within blog content hosted on a WordPress website (via REST API).
It assists in large-scale internal linking by scanning blog posts for paragraphs that mention
specific keywords, and then pairing those paragraphs with relevant target URLs.

🔍 HOW IT WORKS:
1. Loads a list of blog post URLs (`DONOR_FILE`) and a list of keywords with their respective
   target URLs (`KEYWORD_FILE`).
2. Uses the WordPress REST API to fetch each post's HTML content based on its slug.
3. Parses out <p> (paragraph) and <table> blocks using BeautifulSoup.
4. For each keyword, checks whether it's present in any paragraph or in/around a table block.
5. If found, extracts the paragraph as a suitable anchor context for linking.
6. Enforces a max limit of contextual links per post (`MAX_LINKS_PER_POST`) to avoid spammy linking.
7. Results (blog URL, keyword, matched paragraph, target URL) are written to a CSV (`OUTPUT_FILE`).

⚙️ USE CASES:
• SEO teams running interlinking sprints at scale
• Automating content audits for contextual linking gaps
• Feeding this CSV into a generative link rewriter or publishing system

📁 INPUT FILES:
- `second-iteration.csv`: Contains blog post URLs (donors).
- `pages-to-link.csv`: Contains keywords and the target URLs to link to.

📁 OUTPUT FILE:
- `contextual_link_candidates.csv`: Each row suggests a keyword → paragraph match where
   the keyword naturally appears in the post content.

🛡️ SAFEGUARDS:
- Skips paragraphs with fewer than 4 words to reduce noise.
- Avoids creating more than 3 links per post to prevent over-optimization.
- Uses regex word-boundary matching to avoid partial word collisions.
- Includes logic to fallback to nearby paragraphs if keyword is found inside a <table>.

🛠️ TO EXTEND:
- Add GPT scoring for confidence-based ranking.
- Group keyword variants using fuzzy or semantic matching.
- Use append mode and logging for large-scale batch runs.

Author: Daniel Sylvester Antony
Date: 2025
================================================================================
"""

import pandas as pd
import requests
import time
import re
from bs4 import BeautifulSoup
from urllib.parse import urlparse
from base64 import b64encode

# === CONFIG ===
USERNAME = ''
APP_PASSWORD = ''
WP_API_BASE = "https://website.com/blog/wp-json/wp/v2"
auth_str = f"{USERNAME}:{APP_PASSWORD}"
auth_header = {'Authorization': 'Basic ' + b64encode(auth_str.encode()).decode('utf-8')}

DONOR_FILE = 'second-iteration.csv'
KEYWORD_FILE = 'pages-to-link.csv'
OUTPUT_FILE = 'contextual_link_candidates.csv'
MAX_POSTS = 100
MAX_LINKS_PER_POST = 3
DELAY_SECONDS = 1.5

# === HELPERS ===

# Extracts the slug from a blog post URL
def extract_slug(url):
    parsed = urlparse(url)
    return parsed.path.strip('/').split('/')[-1]

# Pulls all paragraph and table blocks from HTML content
def extract_blocks(html):
    soup = BeautifulSoup(html, "html.parser")
    blocks = []
    for el in soup.find_all(['p', 'table']):
        tag_type = el.name
        content = el.get_text().strip().replace('\n', ' ')
        if content:
            blocks.append((tag_type, content))
    return blocks

# Checks if the exact keyword (word-boundary match) exists in a given text
def keyword_in_text(keyword, text):
    pattern = r'\b' + re.escape(keyword) + r'\b'
    return re.search(pattern, text, flags=re.IGNORECASE)

# === MAIN LOGIC ===
def main():
    interlink_df = pd.read_csv(DONOR_FILE)
    pages_df = pd.read_csv(KEYWORD_FILE)

    donor_urls = interlink_df['donor_url'].dropna().unique().tolist()[:MAX_POSTS]
    results = []

    for url in donor_urls:
        slug = extract_slug(url)
        print(f"🔍 Fetching: {slug}")
        try:
            response = requests.get(f"{WP_API_BASE}/posts?slug={slug}", headers=auth_header)
            time.sleep(DELAY_SECONDS)

            if response.status_code == 200 and response.json():
                post = response.json()[0]
                content_html = post['content']['rendered']
                blocks = extract_blocks(content_html)

                seen_pairs = set()
                post_link_count = 0

                for keyword_row in pages_df.itertuples():
                    keyword = str(keyword_row.Keywords).strip().lower()
                    target_url = keyword_row.URL

                    for idx, (block_type, text) in enumerate(blocks):
                        if len(text.split()) < 4:
                            continue  # Ignore short or empty paragraphs

                        pair_key = (url, keyword)
                        if pair_key in seen_pairs:
                            break  # Avoid repeating the same link suggestion for the same keyword

                        if keyword_in_text(keyword, text):
                            if block_type == 'table':
                                # Check surrounding paragraphs if the keyword appears inside a table
                                nearby_blocks = []
                                if idx > 0 and blocks[idx-1][0] == 'p':
                                    nearby_blocks.append(('p_near_table', blocks[idx-1][1]))
                                if idx < len(blocks)-1 and blocks[idx+1][0] == 'p':
                                    nearby_blocks.append(('p_near_table', blocks[idx+1][1]))

                                for para_type, para_text in nearby_blocks:
                                    results.append({
                                        'blog_url': url,
                                        'blog_title': post['title']['rendered'],
                                        'keyword': keyword,
                                        'link_to': target_url,
                                        'paragraph_type': para_type,
                                        'original_paragraph': para_text
                                    })
                                    seen_pairs.add(pair_key)
                                    post_link_count += 1
                                    break

                            elif block_type == 'p':
                                results.append({
                                    'blog_url': url,
                                    'blog_title': post['title']['rendered'],
                                    'keyword': keyword,
                                    'link_to': target_url,
                                    'paragraph_type': 'body_paragraph',
                                    'original_paragraph': text
                                })
                                seen_pairs.add(pair_key)
                                post_link_count += 1
                                break

                        if post_link_count >= MAX_LINKS_PER_POST:
                            break  # Enforce max links per post
            else:
                print(f"⚠️ Failed to fetch: {slug}")
        except Exception as e:
            print(f"❌ Error fetching {slug}: {e}")

    # Output the results
    df_out = pd.DataFrame(results)
    df_out.to_csv(OUTPUT_FILE, index=False)
    print(f"\n✅ Done. Output saved to {OUTPUT_FILE} with {len(results)} rows.")

if __name__ == "__main__":
    main()

import pandas as pd
import openai
import time
import logging
import csv

openai.api_key = 'your-openai-api-key'

INPUT_FILE = 'contextual_link_candidates.csv'
OUTPUT_FILE = 'link_inserted_output.csv'
MODEL = 'gpt-4o-mini'
DELAY = 1.2
RETRIES = 3

logging.basicConfig(filename='link_insertion.log', level=logging.INFO)

def build_prompt(keyword, link_to, paragraph, blog_title):
    return (f"You're an SEO editor. Naturally insert the link [{keyword}]({link_to}) "
            f"into the following paragraph from '{blog_title}' without adding new sentences:\n\n{paragraph}")

df = pd.read_csv(INPUT_FILE)

with open(OUTPUT_FILE, 'a', newline='', encoding='utf-8') as csvfile:
    writer = csv.DictWriter(csvfile, fieldnames=[
        "blog_url", "blog_title", "keyword", "link_to", "original_paragraph", "revised_paragraph"
    ])
    if csvfile.tell() == 0:
        writer.writeheader()

    for row in df.itertuples():
        prompt = build_prompt(row.keyword, row.link_to, row.original_paragraph, row.blog_title)
        success, retries = False, 0
        while not success and retries < RETRIES:
            try:
                response = openai.ChatCompletion.create(
                    model=MODEL,
                    messages=[{"role": "user", "content": prompt}],
                    temperature=0.7, max_tokens=400
                )
                revised_paragraph = response.choices[0].message.content.strip()
                success = True
                writer.writerow({
                    "blog_url": row.blog_url,
                    "blog_title": row.blog_title,
                    "keyword": row.keyword,
                    "link_to": row.link_to,
                    "original_paragraph": row.original_paragraph,
                    "revised_paragraph": revised_paragraph
                })
                logging.info(f"Inserted link for {row.blog_url} using keyword '{row.keyword}'")
            except Exception as e:
                retries += 1
                logging.warning(f"Retry {retries} failed: {e}")
                time.sleep(DELAY * retries)
            time.sleep(DELAY)

print("GPT-powered link insertion complete.")