🚀 Pencraft

AI-powered blog writing toolkit that automates research, planning, and content creation

Features • Installation • Quick Start • Configuration • Documentation • Contributing

---

✨ Features

Feature	Description
🔍 Automated Research	Gathers information from the web with source citations
📈 Google Trends	Validates topics and finds rising/related search queries
📝 Smart Outlining	Dynamically chooses layout (Listicle, Deep Dive, Tutorial)
✍️ Premium Writing	WSJ-style prose, human-like flow, and anti-AI-detection
🔄 Blog Enhancement	Improve existing blogs with SEO, content expansion, and fixes
📄 Hugo Compatible	Outputs markdown with YAML/TOML frontmatter & cover images
⚙️ Fully Configurable	Custom API endpoints, models, prompts, and more
🔌 OpenAI Compatible	Works with any OpenAI-compatible API (local or cloud)
🎨 Beautiful CLI	Rich terminal output with real-time progress indicators

📦 Installation

From Source

# Clone the repository
git clone https://github.com/suhaibbinyounis/pencraft.git
cd pencraft

# Install the package
pip install -e .

# Or with development dependencies
pip install -e ".[dev]"

From PyPI (Coming Soon)

pip install pencraft

🚀 Quick Start

CLI Usage

# Generate a complete blog post
# Generate a premium blog post with cover image
pencraft write "The Future of Remote Work" \
  --words 2000 \
  --cover-image "https://images.unsplash.com/photo-1234.jpg" \
  --output ./blogs \
  --verbose

# Research a topic only
# Research a topic (includes Google Trends analysis)
pencraft research "AI in Healthcare"

# Generate an outline only
pencraft outline "Getting Started with Docker"

# View current configuration
pencraft config --show

# Create a config file
pencraft config --init

# Enhance existing blogs (SEO, content expansion, fixes)
pencraft enhance ./my-blog.md --words 3000

# Enhance entire directory
pencraft enhance ./blogs/ --recursive --words 3000

Python API

from pencraft import Settings
from pencraft.generator import BlogGenerator

# Create generator with custom settings
generator = BlogGenerator(settings=Settings(
    llm={"base_url": "http://localhost:3030/v1", "api_key": "your-key"}
))

# Generate a blog post
blog = generator.generate(
    topic="Introduction to Python",
    target_word_count=2000,
    tags=["python", "programming"],
    output_dir="./output"
)

print(f"Generated: {blog.title} ({blog.word_count} words)")
print(f"Saved to: {blog.file_path}")

Enhance Existing Blogs

from pencraft import BlogEnhancer, Settings

enhancer = BlogEnhancer(settings=Settings())

# Enhance single file
result = enhancer.enhance(
    Path("./my-blog.md"),
    target_word_count=3000,
    improve_seo=True,
    use_trends=True,
)
print(f"Enhanced: {result.original_word_count} → {result.enhanced_word_count} words")

# Batch enhance directory
results = enhancer.enhance_directory(Path("./blogs/"), pattern="*.md")

⚙️ Configuration

Pencraft supports multiple configuration methods:

1. Environment Variables

export PENCRAFT_LLM__BASE_URL="http://localhost:3030/v1"
export PENCRAFT_LLM__API_KEY="your-api-key"
export PENCRAFT_LLM__MODEL="gpt-4"

2. Configuration File

Create pencraft.yaml:

llm:
  base_url: "http://localhost:3030/v1"
  api_key: "your-api-key"
  model: "gpt-4"
  temperature: 0.7

blog:
  min_word_count: 1500
  include_toc: true
  include_citations: true

hugo:
  frontmatter_format: "yaml"

Use with: pencraft write "Topic" --config pencraft.yaml

LLM Provider Setup

LM Studio

1. Download LM Studio
2. Load a model and start the local server
3. Configure: base_url: "http://localhost:1234/v1"

Ollama

1. Install Ollama
2. Run: ollama run llama2
3. Configure: base_url: "http://localhost:11434/v1"

OpenAI

llm:
  base_url: "https://api.openai.com/v1"
  api_key: "sk-your-key"
  model: "gpt-4"

📖 Documentation

Project Structure

pencraft/
├── src/pencraft/
│   ├── agents/         # AI agents (research, planner, writer)
│   ├── config/         # Configuration management
│   ├── formatters/     # Markdown, frontmatter, citations
│   ├── llm/            # OpenAI-compatible client
│   ├── tools/          # DuckDuckGo search, web scraper
│   ├── cli.py          # CLI interface
│   └── generator.py    # Main orchestrator
├── tests/              # Unit tests
├── examples/           # Usage examples
└── pyproject.toml      # Project configuration

CLI Commands

Command	Description
pencraft write <topic>	Generate a complete blog post
pencraft research <topic>	Research a topic only
pencraft outline <topic>	Create a blog outline
pencraft enhance <path>	Enhance existing blog(s) with SEO & content improvements
pencraft config --show	Display current settings
pencraft config --init	Create a config file

Output Example

Generated blogs include proper Hugo frontmatter:

---
title: "Introduction to Machine Learning"
date: 2024-01-15T10:30:00+00:00
draft: false
tags: ["machine-learning", "ai", "tutorial"]
categories: ["Technology"]
toc: true
author: "Pencraft"
---

# Introduction to Machine Learning

## Table of Contents
- [What is Machine Learning?](#what-is-machine-learning)
- [Types of Machine Learning](#types-of-machine-learning)
...

## What is Machine Learning?

Machine learning is a subset of artificial intelligence...

## References

1. [Machine Learning Basics](https://example.com) - Official documentation

🧪 Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Run linting
ruff check src/ tests/
ruff format src/ tests/

# Type checking
mypy src/

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests and linting
5. Commit (git commit -m 'feat: add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with LangChain for AI orchestration
• CLI powered by Typer and Rich
• Web search via DuckDuckGo

---

⬆ Back to Top

Made with ❤️ by Suhaib Bin Younis