AI-Content-Studio

An Intelligent Multi-Agent AI Workflow for Professional Content Creation

Transform a content brief into publication-ready articles through an advanced 3-agent pipeline powered by AI, featuring intelligent quality scoring, adaptive learning, and parallel processing.

🎯 What is AI-Content-Studio?

A sophisticated content creation system that uses three specialized AI agents working in sequence:

WRITER - Generates structured outlines and initial drafts
LLMON - Creates 3 distinct stylistic variations (in parallel)
EDITOR - Applies multi-pass professional polish

✨ What Makes It Special?

🧠 Learns from your feedback - Memory system adapts to your preferences
📊 Objective quality metrics - Multi-dimensional scoring (readability, SEO, engagement)
⚡ 3x faster - Parallel variation generation
🎯 Intelligent validation - Ensures variations are truly different and citations are properly linked
🔄 Iterative refinement - Approve, revise, or reject at each stage
🎨 Flexible providers - OpenAI (GPT-4o/GPT-4.1) or Google Gemini
📝 Dual content modes - General articles OR specialized tool reviews
🔗 Citation validation - Automatic detection of missing hyperlinks and URL verification

🚀 Quick Start (5 Minutes)

1. Install Dependencies

# Clone or download this repository
cd ai-content-studio

# Install Python packages
pip install -r requirements.txt

2. Set Up API Access

Option A: OpenAI (Recommended)

# Run interactive setup
python setup_env.py

# Or manually create .env file:
AI_PROVIDER=openai
OPENAI_API_KEY=sk-proj-your-key-here
OPENAI_WRITER_MODEL=gpt-5-nano
OPENAI_LLMON_MODEL=gpt-4o-mini
OPENAI_EDITOR_MODEL=gpt-4.1-mini

Option B: Google Gemini (Free Tier)

AI_PROVIDER=gemini
GEMINI_API_KEY=your-gemini-key-here

Get API Keys:

OpenAI: https://platform.openai.com/api-keys
Gemini: https://makersuite.google.com/app/apikey

3. Create Your Content Brief

Edit templates/manual.md:

# Article Topic
How AI is transforming content creation in 2025

# Target Audience
Marketing professionals and content creators

# Key Points
- AI-powered workflows save 10+ hours per week
- Multi-agent systems produce higher quality
- [Add your key points...]

4. Run the Workflow

python main.py

That's it! The system will guide you through each stage with interactive prompts.

🌟 Key Features

🎯 Six Intelligence Enhancements (v1.0+)

1. Outline Generation Phase - Plan before writing

Generate and approve article structure before full draft
Iterate on outlines faster than full revisions
Better validation of approach early in process

Example:

→ OUTLINE GENERATION PHASE
→ Generating article outline...

ARTICLE OUTLINE
# Introduction
- Hook: Latest AI statistics
- Thesis: Multi-agent workflows transform content

## Section 1: Current Challenges
- Time constraints in content creation
- Maintaining quality at scale

[Approve/Revise/Reject]

2. Parallel Variation Generation - 3x faster processing

All 3 LLMON variations generate simultaneously
90-180 seconds → 30-60 seconds
No quality compromise

3. Quality Scoring System - Objective metrics for every output

Five-dimensional analysis:

📖 Readability (82/100) - Flesch-Kincaid, grade level, complexity
🔍 SEO (78/100) - Word count, headings, keyword density
💡 Engagement (88/100) - Questions, examples, action verbs
📋 Structure (90/100) - Template matching, completeness
✓ Factual (85/100) - Citation tracking, reference alignment

Overall Score: 85/100

4. Workflow Memory - System learns your preferences

Tracks all feedback across sessions
Extracts patterns from approvals/rejections
Provides historical context to agents
Reduces iterations over time

5. Variation Validation - Ensures true diversity

Automatic differentiation checking (TF-IDF cosine similarity)
Enforces 30% minimum difference threshold
Auto-regeneration if variations too similar
Up to 2 retry attempts

Example Report:

VARIATION DIFFERENTIATION REPORT
Minimum Difference: 45.2%
Average Difference: 52.8%
✓ All variations are sufficiently different!

6. Multi-Pass Editing - Professional polish

Four focused editing passes:

Grammar & Mechanics - Technical correctness (temp: 0.4)
Style & Voice - Tone consistency (temp: 0.5)
Flow & Transitions - Readability (temp: 0.5)
Final Consistency - Validation (temp: 0.4)

Higher quality than single-pass editing.

🔧 Multi-Provider Support (v2.0+)

OpenAI GPT-4o - Premium quality (~$0.43/article)
OpenAI GPT-4.1 - Next-generation models
Google Gemini - Free tier option
Per-agent model configuration - Mix and match models for cost optimization

🎨 Additional Features

✅ Interactive approval gates at each stage
✅ Dynamic rule editing for LLMON variations
✅ Session management - All drafts saved with timestamps
✅ Comprehensive test suite (23 tests, 100% passing)
✅ Rich documentation with guides and examples

📁 Project Structure

AI-Content-Studio/
├── 🚀 ENTRY POINTS
│   ├── main.py                      # Main application
│   ├── run.bat / run.sh             # Quick launch scripts
│   └── setup_env.py                 # Interactive API setup
│
├── ⚙️ CORE SYSTEM
│   ├── workflow.py                  # Orchestrator (3-agent pipeline)
│   ├── config.py                    # Configuration & feature flags
│   ├── api_client.py                # Multi-provider API client
│   └── utils.py                     # Helper functions
│
├── 🤖 AI AGENTS
│   └── agents/
│       ├── writer_agent.py          # Stage 1: Draft + Outline
│       ├── llmon_agent.py           # Stage 2: Parallel variations
│       └── editor_agent.py          # Stage 3: Multi-pass polish
│
├── 🧠 INTELLIGENCE MODULES
│   ├── quality_analyzer.py          # Multi-dimensional scoring
│   ├── workflow_memory.py           # Cross-stage learning
│   ├── variation_differentiator.py  # Variation validation
│   └── citation_validator.py        # Citation & hyperlink validation
│
├── 📝 USER INPUTS (YOU EDIT THESE)
│   ├── templates/
│   │   ├── manual.md                # ⚠️ Your content brief (REQUIRED)
│   │   ├── template.md              # Article structure
│   │   ├── references.md            # Research & data
│   │   ├── writer_prompt.md         # Writing instructions
│   │   ├── tool_review_brief.md     # Tool review input template
│   │   ├── tool_review_structure.md # Review section structure
│   │   └── tool_review_writer_prompt.md # Review writer instructions
│   └── rules/
│       ├── llmon_rules.md           # Variation styles (general)
│       ├── editor_rules.md          # Polish guidelines (general)
│       ├── llmon_tool_review_rules.md    # Tool review variations
│       └── editor_tool_review_rules.md   # Tool review polish
│
├── 📚 DOCUMENTATION
│   └── docs/
│       ├── INDEX.md                 # Complete file navigation
│       ├── guides/
│       │   ├── QUICK_START.md       # 5-minute setup guide
│       │   ├── WORKFLOW_DIAGRAM.md  # Visual workflow
│       │   ├── ENHANCEMENTS_GUIDE.md # Feature deep-dive
│       │   └── TOOL_REVIEW_MODE.md  # Tool review mode guide
│       ├── setup/
│       │   ├── SETUP.md             # Detailed instructions
│       │   └── OPENAI_SETUP_INSTRUCTIONS.md
│       └── project/
│           ├── PROJECT_SUMMARY.md   # System overview
│           ├── CHANGELOG.md         # Version history
│           └── AGENT_ANALYSIS.md    # Technical analysis
│
├── 💡 EXAMPLES
│   └── examples/
│       ├── example_manual.md        # Sample content brief
│       ├── example_references.md    # Sample references
│       ├── example_tool_review_brief.md   # Sample tool review
│       ├── example_tool_review_output.md  # Sample review output
│       ├── template_manual.md       # Template for general articles
│       ├── template_references.md   # Template for references
│       └── template_tool_review_brief.md  # Template for reviews
│
├── 📊 OUTPUTS (AUTO-GENERATED)
│   └── outputs/
│       └── [timestamp]/
│           ├── 01_writer_outline.md
│           ├── 01_writer_draft.md
│           ├── 02_llmon_variation1.md (+ quality scores)
│           ├── 02_llmon_variation2.md
│           ├── 02_llmon_variation3.md
│           ├── 03_editor_polished.md
│           └── FINAL_ARTICLE.md     # ✨ Final output
│
├── 🧪 TESTING
│   ├── test_setup.py                # Setup verification
│   ├── test_enhancements.py         # Feature tests (23 tests)
│   └── test_citation_validator.py   # Citation validation tests
│
├── 💾 MEMORY (AUTO-CREATED)
│   └── memory/                      # Persistent learning data
│
└── 📋 CONFIG
    ├── .env                         # API keys (YOU CREATE THIS)
    ├── requirements.txt             # Dependencies
    └── README.md                    # This file

🔄 The 3-Agent Workflow

Stage 1: WRITER Agent

What Happens:

Outline Phase - Creates structured outline from your brief
Review - You approve, revise, or reject the outline
Full Draft - Generates complete article from approved outline
Quality Score - Provides multi-dimensional quality metrics

Your Inputs:

templates/manual.md - Content brief (required)
templates/template.md - Article structure
templates/references.md - Research materials
templates/writer_prompt.md - Writing instructions

Approval Options:

✓ Approve → Continue to LLMON
✎ Revise with feedback → Regenerate with your input
✗ Reject → Stop workflow

Stage 2: LLMON Agent

What Happens:

Parallel Generation - Creates 3 distinct variations simultaneously
Differentiation Check - Validates variations are >30% different
Quality Scoring - Analyzes each variation
Comparison - Presents all 3 with differentiation report

Your Inputs:

rules/llmon_rules.md - Stylistic transformation rules
Previous stage approved article

Approval Options:

Select Variation 1/2/3 → Continue to EDITOR
↻ Iterate with edited rules → Modify rules, regenerate
✗ Reject all → Stop workflow

Stage 3: EDITOR Agent

What Happens:

Pass 1: Grammar - Technical correctness
Pass 2: Style - Tone and voice consistency
Pass 3: Flow - Readability and transitions
Pass 4: Consistency - Final validation
Quality Score - Final quality assessment

Your Inputs:

rules/editor_rules.md - Polish guidelines
Selected variation from Stage 2

Approval Options:

✓ Approve as final → Complete! Save to FINAL_ARTICLE.md
✎ Request revisions → Provide specific feedback
✗ Reject → Stop workflow

📊 Quality Scoring Explained

Every output receives a comprehensive quality analysis:

QUALITY ANALYSIS REPORT
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Overall Score: 85/100

📖 Readability: 82/100
   • Grade Level: 10 (General Adult)
   • Reading Ease: 65.2 (Standard)
   • Avg Sentence Length: 18.3 words
   • Complex Word %: 12.4%

🔍 SEO: 78/100
   • Word Count: 1,847 ✓
   • Headings: 8 ✓
   • Keyword Density: 2.1% ✓
   • URL-friendly: Yes

💡 Engagement: 88/100
   • Questions: 5
   • Examples: 7
   • Action Verbs: High
   • Emotional Words: Moderate

📋 Structure: 90/100
   • Template Match: 95%
   • Section Completeness: 100%
   • Logical Flow: Excellent

✓ Factual Consistency: 85/100
   • Reference Alignment: High
   • Citation Count: 6
   • Keyword Overlap: 78%

⚙️ Configuration Guide

Feature Toggles (config.py)

All enhancements enabled by default:

# Enhancement Feature Flags
ENABLE_OUTLINE_PHASE = True           # Outline generation
ENABLE_PARALLEL_VARIATIONS = True     # 3x speed boost
ENABLE_QUALITY_SCORING = True         # Objective metrics
ENABLE_WORKFLOW_MEMORY = True         # Learning system
ENABLE_VARIATION_VALIDATION = True    # Differentiation check
ENABLE_MULTIPASS_EDITING = True       # 4-pass polish

AI Provider Configuration

OpenAI (Per-Agent Models):

AI_PROVIDER=openai
OPENAI_API_KEY=sk-proj-...

# Different models for different agents
OPENAI_WRITER_MODEL=gpt-5-nano        # Fast drafting
OPENAI_LLMON_MODEL=gpt-4o-mini        # Creative variations
OPENAI_EDITOR_MODEL=gpt-4.1-mini      # Premium polish

Google Gemini (Simple):

AI_PROVIDER=gemini
GEMINI_API_KEY=your-key-here

Agent Temperature Settings

WRITER_TEMPERATURE = 0.7   # Balanced creativity
LLMON_TEMPERATURE = 0.8    # Higher for variation diversity
EDITOR_TEMPERATURE = 0.5   # Lower for consistency

💡 Usage Tips & Best Practices

✅ For Best Results

Write Detailed Briefs - More detail in manual.md = better output
Use References Liberally - Add data, examples, research to references.md
Customize Templates - Adjust template.md for your specific format
Leverage Memory - System improves over multiple sessions
Monitor Quality Scores - Use metrics to identify weak areas
Iterate Strategically - Use outline revisions for structure, feedback for content

📝 Example Use Cases

Blog Posts - Optimized for engagement and SEO
Technical Articles - Structured with clarity and accuracy
Marketing Content - Persuasive with strong calls-to-action
Educational Guides - Clear explanations with examples
Product Descriptions - Benefit-focused with features
Industry Analyses - Data-driven with insights

⚡ Performance Tips

Parallel processing saves ~90 seconds per LLMON iteration
Outline approval reduces wasted time on wrong structure
Quality scores help identify issues before final polish
Memory system reduces iterations after 2-3 sessions

🔧 Tool Review Mode

NEW: Generate professional, story-driven software/tool reviews optimized for both humans and LLMs.

What's Different?

Tool Review Mode creates personable, evidence-backed reviews with a specialized workflow:

Feature	General Article	Tool Review
Voice	Professional, flexible	First-person, story-driven
Evidence	Optional citations	Required 6-10 user quotes
Structure	Flexible template	Fixed review sections
Format	Standard	Strict (no em dashes, clean headers)
Pricing	Not required	Detailed breakdown required

Quick Start

1. Set Mode:

CONTENT_MODE=tool_review

2. Fill Out Brief: Use templates/tool_review_brief.md:

Answer 4 pre-writing questions (title, audience, motivation, benefit)
Collect 6-10 quotes from G2, Capterra, Reddit, etc.
Document pricing, migration paths, implementation steps
Gather review hub ratings (G2, Capterra)

3. Run Workflow:

python main.py

Output Includes

✅ Story-driven narrative with first-person voice
✅ 6-10 integrated user quotes (from G2, Reddit, Capterra, etc.)
✅ Conditional framing: "If you're X... if you're Y..."
✅ Detailed pricing breakdown with scaling info
✅ Honest pros, cons, and fit analysis
✅ Migration paths (switching to/from tool)
✅ Implementation steps (realistic setup)
✅ Sources appendix with all quote URLs

Example

See examples/example_tool_review_output.md for a complete Surfer SEO review demonstrating all required elements.

Learn More

📚 Complete Tool Review Mode Guide - Detailed walkthrough, best practices, troubleshooting

🔧 Advanced Customization

Modify Agent Behavior

LLMON Variations: Edit rules/llmon_rules.md:

# Variation 1: Professional
- Formal tone, executive audience
- Data-driven, authoritative

# Variation 2: Conversational
- Casual, friendly, relatable
- Story-driven, examples

# Variation 3: Technical
- Detailed, precise, expert-level
- Code examples, specifications

Editor Standards: Edit rules/editor_rules.md to adjust polish criteria.

Change Article Structure

Edit templates/template.md:

# [Your Custom Structure]

## Introduction (100-150 words)
- Hook
- Context
- Thesis

## Main Sections (3-5 sections, 300-500 words each)
[Your requirements...]

## Conclusion (100-150 words)
- Summary
- Call-to-action

Adjust Quality Thresholds

# In quality_analyzer.py
MIN_VARIATION_DIFFERENCE = 0.3  # 30% minimum (0-1 scale)

💰 Cost Analysis

OpenAI GPT-4o (Typical Usage)

Metric	Estimate
Input tokens per article	~50,000
Output tokens per article	~30,000
Input cost	$0.125 ($2.50/1M)
Output cost	$0.300 ($10.00/1M)
Total per article	~$0.43
Articles from $10	~23 articles

Google Gemini (Free Tier)

Cost: $0.00
Limit: 15 requests/minute
Best for: Testing, low-volume use

💡 Tip: Use cheaper models (gpt-5-nano) for Writer/LLMON, premium (gpt-4.1) for Editor only!

📚 Full Documentation

This README provides a comprehensive overview. For deeper details:

📖 Complete File Index - Navigate all project files
🚀 Quick Start Guide - 5-minute setup
🔧 Setup Instructions - Detailed configuration
📊 Workflow Diagrams - Visual guides
✨ Enhancements Guide - Feature deep-dive
📝 Tool Review Mode Guide - Complete tool review workflow NEW
📝 Changelog - Version history (v1.0 → v3.0)
🏗️ Project Summary - Technical overview
🤖 Agent Analysis - Agent architecture

✅ Testing & Verification

Run Setup Verification

python test_setup.py

Checks:

✅ Python version (3.8+)
✅ All dependencies installed
✅ API keys configured
✅ Template files exist
✅ Directory structure

Run Enhancement Tests

python test_enhancements.py

Results:

✅ 23 tests total
✅ 23 passing
✅ 0 failing
🕐 Execution: ~1 second

❓ Troubleshooting

Common Issues

"API key not found"

Solution:

Check .env file exists in root directory
Verify variable name: OPENAI_API_KEY or GEMINI_API_KEY
No quotes needed around key value
Run python setup_env.py for interactive setup

"Missing model configuration"

Solution (OpenAI):

OPENAI_WRITER_MODEL=gpt-5-nano
OPENAI_LLMON_MODEL=gpt-4o-mini
OPENAI_EDITOR_MODEL=gpt-4.1-mini

All three required for OpenAI provider.

"File not found" errors

Solution:

Check templates/manual.md exists and has content
Verify working directory: cd ai-content-studio
Copy from examples: cp examples/example_manual.md templates/manual.md

Poor output quality

Solutions:

✅ Add more detail to templates/manual.md
✅ Include data in templates/references.md
✅ Check quality scores for weak areas
✅ Provide specific feedback in revision loops
✅ Customize template.md for your needs

API rate limits

Solutions:

Gemini free tier: 15 requests/minute
OpenAI: Check limits at https://platform.openai.com/settings/organization/limits
Wait briefly between runs or upgrade tier

🗺️ Roadmap & Future Enhancements

Potential Future Features

📄 License & Credits

License: MIT - Free to use and modify for your content creation needs.

Credits:

Built with Python, OpenAI GPT-4o/4.1, Google Gemini
Quality analysis: TextStat, scikit-learn
CLI: Colorama

🆘 Support & Resources

Getting Help

Read the docs: Start with docs/INDEX.md
Check examples: See examples/ directory
Run tests: python test_setup.py to verify setup
Review changelog: docs/project/CHANGELOG.md

External Resources

OpenAI API Keys: https://platform.openai.com/api-keys
OpenAI Pricing: https://openai.com/api/pricing/
Gemini API Keys: https://makersuite.google.com/app/apikey
Python Downloads: https://www.python.org/downloads/

🎉 Get Started Now!

# 1. Install dependencies
pip install -r requirements.txt

# 2. Set up API access
python setup_env.py

# 3. Edit your content brief
# Open templates/manual.md and add your topic

# 4. Run the workflow
python main.py

# 🚀 Watch the magic happen!

Built with ❤️ for efficient, intelligent, scalable content creation

AI-Content-Studio v3.0 - October 2025

Name		Name	Last commit message	Last commit date
Latest commit History 16 Commits
.cursor/plans		.cursor/plans
agents		agents
docs		docs
examples		examples
memory		memory
rules		rules
templates		templates
.gitignore		.gitignore
README.md		README.md
api_client.py		api_client.py
citation_validator.py		citation_validator.py
config.py		config.py
main.py		main.py
quality_analyzer.py		quality_analyzer.py
requirements.txt		requirements.txt
run.bat		run.bat
run.sh		run.sh
setup_env.py		setup_env.py
test_citation_validator.py		test_citation_validator.py
test_enhancements.py		test_enhancements.py
test_setup.py		test_setup.py
utils.py		utils.py
variation_differentiator.py		variation_differentiator.py
workflow.py		workflow.py
workflow_memory.py		workflow_memory.py

Folders and files

Latest commit

History

Repository files navigation

AI-Content-Studio

🎯 What is AI-Content-Studio?

✨ What Makes It Special?

🚀 Quick Start (5 Minutes)

1. Install Dependencies

2. Set Up API Access

3. Create Your Content Brief

4. Run the Workflow

🌟 Key Features

🎯 Six Intelligence Enhancements (v1.0+)

🔧 Multi-Provider Support (v2.0+)

🎨 Additional Features

📁 Project Structure

🔄 The 3-Agent Workflow

Stage 1: WRITER Agent

Stage 2: LLMON Agent

Stage 3: EDITOR Agent

📊 Quality Scoring Explained

⚙️ Configuration Guide

Feature Toggles (config.py)

AI Provider Configuration

Agent Temperature Settings

💡 Usage Tips & Best Practices

✅ For Best Results

📝 Example Use Cases

⚡ Performance Tips

🔧 Tool Review Mode

What's Different?

Quick Start

Output Includes

Example

Learn More

🔧 Advanced Customization

Modify Agent Behavior

Change Article Structure

Adjust Quality Thresholds

💰 Cost Analysis

OpenAI GPT-4o (Typical Usage)

Google Gemini (Free Tier)

📚 Full Documentation

✅ Testing & Verification

Run Setup Verification

Run Enhancement Tests

❓ Troubleshooting

Common Issues

🗺️ Roadmap & Future Enhancements

Potential Future Features

📄 License & Credits

🆘 Support & Resources

Getting Help

External Resources

🎉 Get Started Now!

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages