Article Generator

A Python tool for generating technical and educational articles based on specified topics using AI. The system creates well-structured Markdown content that follows a consistent format, with transparency into the AI's decision-making process.

Features

• Generate complete articles with introduction, body sections, and conclusion
• Create content with appropriate structure and formatting
• Direct Markdown generation without intermediate steps
• Support for code snippets and image placeholders
• Customizable word count
• Detailed planning and execution process
• Transparent AI reasoning for each generation step
• Saves outputs as Markdown and JSON for further processing

Sample Articles

Here are some examples of articles generated with this tool:

1. Introduction to Machine Learning for Beginners (1,200 words)
2. Introduction to Dimensionality Reduction (3,000 words)
3. Introduction to Artificial Intelligence: From Neural Networks to Deep Learning (4,500 words)
4. PID Controller: A Comprehensive Guide (3,000 words)
5. Cognitive Biases: A Comprehensive Review (5,000 words)
6. Logical Fallacies: A Practical Guide to Critical Thinking (5,000 words)
7. A Beginner's Guide to Functional Programming (3,000 words)
8. Git Demystified: How Version Control Powers Modern Software Development (2,500 words)
9. Teaching Kids to Code: A Curriculum Blueprint (4,000 words)
10. How Language Shapes Thought: An Exploration of Linguistic Relativity (4,000 words)

Requirements

• Python 3.8+
• pydantic-ai package (for AI agent functionality)
• Access to the specified AI model (default: gpt-4.1)

Installation

1. Clone this repository
2. Install the required dependencies:

pip install pydantic pydantic-ai

Usage

Basic Usage

python main.py "Your Article Topic" --word_count 1500

Additional command-line options:

python main.py "Your Topic" --word_count 1500 --model "gpt-4.1" --output_dir "my_articles" --no_save

Example Script

Run the included example script:

python example.py

This will generate an article on "Introduction to Machine Learning for Beginners" with approximately 1200 words.

Using the API in Your Code

import article_generator as ag

# Simple usage with the convenience function
markdown_content = ag.generate_article("Your Article Topic", word_count=1500)

# Or using the ArticleGenerator class for more control
generator = ag.ArticleGenerator(model="gpt-4.1", output_dir="my_articles")
markdown_content, article_data = generator.generate(
    "Your Article Topic", 
    word_count=1500,
    save_output=True
)

# Use the generated markdown content
print(markdown_content)

# Access the AI's reasoning for any component
print(article_data["plan"]["reasoning"]["description"])

System Design

The article generation system consists of two main components:

1. PlannerAgent: Creates a detailed outline for the article based on the topic and word count
2. ContentWriterAgent: Writes the content for each section of the article directly in Markdown format

The main workflow is coordinated by the ArticleGenerator class or the convenience function generate_article.

The system follows this workflow:

1. Plan the article structure
2. Write content for each section (introduction, body sections, conclusion)
3. Combine all sections into a complete article
4. Save the results (if requested)

Reasoning Field

A key design feature of this system is the inclusion of a "reasoning" field in each response from the AI. This provides:

• Transparency: Understand why the AI made specific content and structural decisions
• Quality Control: Assess whether the AI's thought process aligns with expectations
• Debugging: Identify where issues might occur in the generation process
• Educational Value: Learn from the AI's approach to content organization and creation
• Improvement Insights: Gather information to refine prompts and system design

The reasoning is captured at each stage (planning, section writing) and stored in the JSON output for analysis.

Output

The system generates the following outputs in the output/article-{timestamp} directory:

• article.md: The complete article in Markdown format
• article.json: Detailed JSON data about the article structure and content, including AI reasoning
• project.json: Project metadata

Customization

The system can be customized by modifying the agent prompts in article_generator/agents.py or by adjusting the data models in article_generator/types.py.

Author

Mostapha Kalami Heris

Connect with the author:

• LinkedIn: linkedin.com/in/smkalami
• GitHub: github.com/smkalami
• Twitter/X: x.com/smkalami
• Medium: kalami.medium.com

License

MIT License