CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a SEO Article Generator - a Gradio-based web application that generates SEO-optimized articles using OpenAI's GPT models. The application allows users to input context and keywords, then generates articles that match the style and quality of reference articles stored in articles.txt.

Key Files and Structure

• app.py - Main application file containing the entire Gradio interface and business logic
• articles.txt - Reference articles database used to guide writing style and quality
• .env - Environment variables (contains OPENAI_API_KEY)

Development Commands

Running the Application

python app.py

Environment Setup

# Create .env file with:
echo "OPENAI_API_KEY=your_openai_key_here" > .env

# Install dependencies (if requirements.txt exists):
pip install -r requirements.txt

# Otherwise install manually:
pip install gradio requests python-dotenv

Testing

• Manual Testing: Run the app and test through the Gradio interface at http://localhost:7862
• API Testing: Test OpenAI API connectivity by running article generation

Code Architecture

Core Classes

1. Config (app.py:16-28) - Central configuration management

   • OpenAI API key handling
   • Model configurations (gpt-4o-mini, gpt-4o, gpt-4-turbo-preview)
   • File path constants

2. ArticleKnowledgeBase (app.py:30-52) - Reference articles management

   • Loads and manages content from articles.txt
   • Provides context for AI article generation
   • Handles file reading errors gracefully

3. SEOArticleGenerator (app.py:54-209) - Core article generation logic

   • OpenAI API integration
   • Prompt engineering for SEO optimization
   • Article editing functionality
   • Keyword tracking and analysis

4. SEOArticleBot (app.py:211-274) - Application interface layer

   • Gradio interface integration
   • User input validation
   • Response formatting and status reporting

Key Features

• Article Generation: Creates SEO-optimized articles based on context and keywords
• Article Editing: Allows users to refine existing articles with specific instructions
• Keyword Tracking: Monitors keyword usage and density
• Reference Style Matching: Uses articles.txt content to maintain consistent writing style
• Multiple AI Models: Supports different OpenAI GPT models with quality/speed tradeoffs

Prompt Engineering

The system uses sophisticated prompt engineering (app.py:84-124) with:

• System prompts defining expert SEO writer persona
• Writing guidelines for style, SEO requirements, structure, and quality
• Context integration from reference articles
• Keyword optimization with natural incorporation requirements

Error Handling

• API Key Validation: Checks for OpenAI API key before requests
• File Loading: Graceful handling of missing articles.txt
• API Error Handling: Comprehensive error reporting for OpenAI API failures
• Input Validation: Ensures required fields are provided

Reference Articles System

The articles.txt file contains reference articles that guide the AI's writing style. Current articles focus on:

• Video marketing strategies
• Small business video needs
• OTT advertising benefits
• Business video types
• Brand awareness and conversions

When adding new reference articles, maintain the format:

## Article [Number]

[Article Title]
[Article Content]

Configuration Notes

• Default Model: gpt-4o (balanced quality/speed)
• Server Configuration: Runs on 0.0.0.0:7862 with sharing enabled
• Article Length: Targets 800-1500 words
• Keyword Density: Maintains 1-2% without stuffing
• Temperature: 0.7 for balanced creativity and consistency

Development Tips

• Test OpenAI API connectivity before making changes
• The reference articles significantly impact output quality - update them regularly
• Keyword tracking helps optimize SEO performance
• Use the edit feature for iterative improvements rather than regenerating
• Monitor API usage and costs when testing

Deployment Considerations

• Ensure .env file is properly configured and secure
• articles.txt should be populated with high-quality reference content
• Consider rate limiting for production usage
• Monitor OpenAI API usage and costs
• The app auto-generates sharing links - may need to disable for production