Skip to main content

Ghost Blog Smart

🚀 A comprehensive solution for Ghost CMS blog management with AI-powered features

Available as both a Python Package and REST API with multiple deployment options including Docker, local installation, and PyPI package.

PyPI version Docker Hub GitHub Actions License: MIT Python 3.9+

🎯 Choose Your Setup Method

Method Best For Example Files Documentation Section
🐳 Docker API Production deployment, quick testing example_usage_API.js Docker Deployment
🐍 Python Package Python developers, scripting example_usage.py Python Package
🌐 Local API Development, customization example_usage_API.js Local API Setup
📦 PyPI Install Simple Python integration example_usage.py PyPI Installation

📖 Table of Contents

🚀 Getting Started

📚 Usage Examples

📖 Documentation


🐳 Docker Deployment

Recommended for: Production environments, quick testing, isolation

Example File: example_usage_API.js (Node.js client for REST API)

Quick Start

# Pull and run the pre-built Docker image
docker pull betashow/ghost-blog-smart-api:latest

# Run with your credentials
docker run -d \
  -p 5000:5000 \
  -e GHOST_ADMIN_API_KEY="your_key_id:your_secret_key" \
  -e GHOST_API_URL="https://your-ghost-site.com" \
  -e GEMINI_API_KEY="your_gemini_key" \
  -e REPLICATE_API_TOKEN="r8_your_replicate_token" \
  -e FLASK_API_KEY="your_secure_api_key" \
  --name ghost-blog-api \
  betashow/ghost-blog-smart-api:latest

# Test the API
curl http://localhost:5000/health

Docker Compose

version: '3.8'
services:
  ghost-blog-smart-api:
    image: betashow/ghost-blog-smart-api:latest
    ports:
      - "5000:5000"
    environment:
      - GHOST_ADMIN_API_KEY=your_key_id:your_secret_key
      - GHOST_API_URL=https://your-ghost-site.com
      - GEMINI_API_KEY=your_gemini_key
      - REPLICATE_API_TOKEN=r8_your_replicate_token
      - FLASK_API_KEY=your_secure_api_key

Next Steps:


🐍 Python Package Usage

Recommended for: Python developers, scripting, direct integration

Example File: example_usage.py (Pure Python usage)

Installation

pip install ghost-blog-smart

Basic Usage

from ghost_blog_smart import smart_blog_gateway

# Smart Gateway Method (Recommended)
result = smart_blog_gateway(
    "AI healthcare benefits: faster diagnosis, better accuracy, cost reduction",
    status="published"
)

if result['success']:
    print(f"Post created: {result['url']}")

Next Steps:


📦 PyPI Installation

Recommended for: Simple Python projects, minimal setup

# Install from PyPI
pip install ghost-blog-smart

# Use directly in your Python code
from ghost_blog_smart import create_ghost_blog_post, smart_blog_gateway

Create .env file with your credentials:

GHOST_ADMIN_API_KEY=your_admin_api_key_id:your_secret_key_here
GHOST_API_URL=https://your-ghost-site.com
GEMINI_API_KEY=your_gemini_api_key_here
REPLICATE_API_TOKEN=r8_your_replicate_api_token_here

🌐 Local API Development

Recommended for: Development, customization, testing

Example Files: example_usage_API.js (Node.js client) + Local Flask API

Setup

# Clone the repository
git clone https://github.com/preangelleo/ghost_blog_smart.git
cd ghost_blog_smart

# Install dependencies
pip install -r requirements.txt
pip install -r requirements-api.txt
pip install -e .

# Set up environment variables
cp .env.example .env
# Edit .env with your credentials

# Run the Flask API
python app.py

API runs on: http://localhost:5000

Next Steps:


💻 Python Examples (example_usage.py)

For: Python Package usage, PyPI installation, direct Python integration

Key Examples from example_usage.py:

Smart Gateway (AI-Enhanced Creation)

from ghost_blog_smart import smart_blog_gateway

result = smart_blog_gateway(
    "Write about AI benefits in healthcare: faster diagnosis, better accuracy",
    status="published",
    preferred_language="English"
)

Traditional Method

from ghost_blog_smart import create_ghost_blog_post

result = create_ghost_blog_post(
    title="My Blog Post",
    content="Post content in **Markdown**",
    excerpt="Brief summary",
    tags=["Tutorial", "AI"],
    status="published",
    use_generated_feature_image=True,
    prefer_flux=True
)

Blog Management

from ghost_blog_smart import get_ghost_posts, update_ghost_post, delete_ghost_post

# Get posts
posts = get_ghost_posts(limit=5, status='published')

# Update post
update_ghost_post(post_id="abc123", featured=True)

# Delete post
delete_ghost_post(post_id="abc123")

📁 Complete examples available in: example_usage.py


🌐 Node.js API Examples (example_usage_API.js)

For: Docker deployment, local API server, REST API integration

Prerequisites

npm install axios  # HTTP client for API calls

Key Examples from example_usage_API.js:

Configuration

const CONFIG = {
    baseUrl: 'http://localhost:5000',
    apiKey: 'your_secure_api_key',
    timeout: 300000, // 5 minutes for image generation
    imageTimeout: 300000, // Extended timeout for image endpoints
    standardTimeout: 30000, // Standard timeout for other endpoints
};

Create Blog Post via API

const postData = {
    title: "My API Blog Post",
    content: "Post content in **Markdown**",
    excerpt: "Brief summary",
    tags: ["API", "Node.js"],
    status: "published",
    use_generated_feature_image: true,
    prefer_flux: true,
    image_aspect_ratio: "16:9"
};

const response = await api.post('/api/posts', postData);

Smart Create via API

const smartData = {
    user_input: "Write about JavaScript testing frameworks: Jest vs Mocha vs Cypress",
    status: "draft",
    preferred_language: "English"
};

const response = await api.post('/api/smart-create', smartData);

Running Tests

# Run all endpoint tests
node example_usage_API.js

# Run specific test
node example_usage_API.js health

# Run with custom timeout (5 minutes for image generation)
node example_usage_API.js --timeout 300000

# Production mode (creates real posts)
node example_usage_API.js --production

📁 Complete examples available in: example_usage_API.js


✨ Features

🤖 Smart AI Gateway

  • Intelligent Routing - Automatically determines if content needs rewriting
  • Structured Output - Uses Gemini's structured output for consistent formatting
  • Function Calling - Leverages Gemini function calling for smart decision making
  • Auto Enhancement - Transforms scattered ideas into complete blog posts
  • Missing Component Detection - Automatically generates titles, excerpts, and tags

🎨 Dual AI Image Generation

  • 🔥 Replicate Flux-dev: Ultra-fast generation (3-7 seconds), photorealistic images, WebP format
  • 🏔️ Google Imagen-4: Professional quality, advanced prompt understanding, PNG format
  • Automatic Fallback System: Intelligent provider switching for maximum reliability
  • Provider Selection: Choose your preferred provider or let the system decide
  • Multiple Aspect Ratios: 16:9, 1:1, 9:16, 4:3, 3:2 support

📝 Content Management

  • Smart Content Formatting - Auto-format plain text to beautiful Markdown with Gemini AI
  • YouTube-Style Slugs - Generate 11-character slugs like YouTube video IDs
  • Multi-language Support - Chinese to Pinyin conversion for slugs
  • Language Translation - Auto-translate content to any target language
  • Flexible Image Handling - Support for URLs, local files, base64 data

📊 Blog Management

  • Advanced Listing - Get posts with powerful filtering options
  • Search & Query - Full-text search across all posts
  • Date Range Filtering - Find posts by publication/creation date
  • Update & Delete - Modify or remove posts with comprehensive options
  • Batch Operations - Process multiple posts efficiently
  • Detailed Analytics - Get complete post details and summaries

🔧 REST API Reference

Base URL Structure

http://localhost:5000/          # API information
http://localhost:5000/health    # Health check
http://localhost:5000/api/      # All blog endpoints

Authentication

All API endpoints (except / and /health) require authentication:

curl -H "X-API-Key: your_api_key" http://localhost:5000/api/posts

Standard Response Format

{
  "success": true,
  "timestamp": "2024-01-01T00:00:00.000000Z",
  "data": {
    // Response data here
  }
}

⚠️ TIMEOUT CONFIGURATION NOTICE

  • Image Generation Endpoints: /api/posts (with use_generated_feature_image: true) and /api/posts/{id}/image require extended timeouts
  • Recommended Client Timeout: 5 minutes (300 seconds) minimum
  • Typical Response Times: 60-300 seconds for image generation
  • Without Images: Standard 30-second timeout is sufficient

📝 Core Endpoints

Create Blog Post ⚠️ Extended Timeout for Images

POST /api/posts
Content-Type: application/json
X-API-Key: your_api_key

{
  "title": "My Blog Post",
  "content": "Post content in **Markdown**",
  "excerpt": "Brief summary",
  "tags": ["Tag1", "Tag2"],
  "status": "published",
  "use_generated_feature_image": true,
  "prefer_flux": true,
  "image_aspect_ratio": "16:9"
}

⏱️ Important: When use_generated_feature_image: true is used, generation can take 60-300 seconds. Set client timeout to at least 5 minutes (300 seconds).

Smart Create (AI-Enhanced)

POST /api/smart-create
Content-Type: application/json
X-API-Key: your_api_key

{
  "user_input": "Write about AI benefits in healthcare",
  "status": "draft",
  "preferred_language": "English"
}

Get Posts

GET /api/posts?limit=5&status=published&featured=true
X-API-Key: your_api_key

Update Post Image ⚠️ High Timeout Required

PUT /api/posts/{post_id}/image
Content-Type: application/json
X-API-Key: your_api_key

{
  "use_generated_feature_image": true,
  "prefer_imagen": true,
  "image_aspect_ratio": "16:9"
}

⏱️ Important: Image generation endpoints can take 60-300 seconds to complete. Set client timeout to at least 5 minutes (300 seconds) for reliable operation.

📋 Complete Endpoint List

Endpoint Method Description Auth Required Timeout
/ GET API information ❌ Standard
/health GET Health check ❌ Standard
/api/posts POST Create blog post ✅ Extended*
/api/smart-create POST AI-enhanced creation ✅ Standard
/api/posts GET List posts ✅ Standard
/api/posts/advanced GET Advanced search ✅ Standard
/api/posts/{id} GET Get post details ✅ Standard
/api/posts/{id} PUT/PATCH Update post ✅ Standard
/api/posts/{id} DELETE Delete post ✅ Standard
/api/posts/{id}/image PUT Update post image ✅ Extended*
/api/posts/summary GET Posts summary ✅ Standard
/api/posts/batch-details POST Batch get details ✅ Standard
/api/posts/search/by-date-pattern GET Date search ✅ Standard

*Extended = 5 minutes (300 seconds) for image generation


⏱️ Performance & Timeout Guidelines

Image Generation Performance

  • Replicate Flux: 3-7 seconds (ultra-fast)
  • Google Imagen: 10-15 seconds (professional quality)
  • Upload & Processing: Additional 45-60 seconds
  • Total Time: 60-300 seconds for complete image generation
// For endpoints WITH image generation
const imageApiTimeout = 300000; // 5 minutes

// For endpoints WITHOUT image generation  
const standardTimeout = 30000; // 30 seconds

Production Testing Results

✅ All endpoints functional
⚠️ Image generation requires extended timeout
💡 Recommendation: Always set 5-minute timeout for image endpoints


🧪 Testing

Python Package Testing

# Set test mode to avoid actual posting
python example_usage.py  # Uses is_test=True by default

API Testing (Docker/Local)

# Comprehensive test suite
node example_usage_API.js

# Individual endpoint tests
node example_usage_API.js health
node example_usage_API.js create
node example_usage_API.js smart

# Production mode (creates real posts)
node example_usage_API.js --production

# Extended timeout for image generation
node example_usage_API.js --timeout 300000

Docker Testing Guide

See TESTING_GUIDE.md for comprehensive Docker testing instructions.


📁 Project Structure

ghost-blog-smart/
├── ghost_blog_smart/             # Main Python package
│   ├── __init__.py              # Package exports
│   ├── main_functions.py        # Core API functions
│   ├── smart_gateway.py         # AI-powered routing
│   ├── post_management.py       # Advanced management
│   └── *.py                    # Other modules
├── example_usage.py             # 🐍 Python package examples
├── example_usage_API.js         # 🌐 Node.js API client examples  
├── app.py                       # 🚀 Flask REST API server
├── Dockerfile                   # 🐳 Docker configuration
├── docker-compose.yml          # 🐳 Docker Compose setup
├── requirements.txt             # Python dependencies
├── setup.py                    # PyPI package setup
├── TESTING_GUIDE.md            # 🧪 Docker testing instructions
└── README.md                   # 📖 This documentation

🎨 Image Generation Comparison

Feature Replicate Flux-dev Google Imagen-4
Speed ⚡ Ultra-fast (3-7s) 🐢 Moderate (10-15s)
Quality 🔥 Photorealistic 🏔️ Professional
Format 📁 WebP (smaller) 📁 PNG (lossless)
Cost 💰 Pay-per-use 💰 API quota based
Best For Realistic scenes, portraits Abstract concepts, artistic

Supported Aspect Ratios:

  • 16:9 - Widescreen (1920x1080) - Default
  • 1:1 - Square (1024x1024) - Great for social media
  • 9:16 - Portrait (1080x1920) - Mobile-optimized
  • 4:3 - Traditional (1024x768) - Classic photo ratio
  • 3:2 - DSLR (1536x1024) - Professional photography

📋 Prerequisites

  • Python 3.8+
  • Ghost CMS instance with Admin API access
  • Image Generation (choose one or both):
    • Google Gemini API key (for Imagen-4 generation)
    • Replicate API token (for Flux-dev generation)

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.


📄 License

MIT License - see LICENSE file for details


🙏 Acknowledgments

  • Ghost CMS for the excellent blogging platform
  • Google Gemini & Imagen for AI capabilities
  • Replicate for ultra-fast Flux generation
  • The open-source community

📞 Support

For issues or questions, please open an issue on GitHub.


Made with ❤️ for the Ghost CMS community

✨ Available as both Python Package and REST API with comprehensive Docker support!

Metadata

Release files for ghost-blog-smart 1.1.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distribution (wheel)

Table of built distributions (wheels) for ghost-blog-smart 1.1.3
File Interpreter ABI Platform Actions
ghost_blog_smart-1.1.3-py3-none-any.whl Python 3 none any Details for ghost_blog_smart-1.1.3-py3-none-any.whl

Release files / ghost_blog_smart-1.1.3-py3-none-any.whl

Download URL ghost_blog_smart-1.1.3-py3-none-any.whl
Size 58.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
95affe8c99749b07745e377a3f3a4ba51b0ecf9ea04a0a40abd001b87a084f65
BLAKE2b-256 checksum
How to use checksums
e633efc7f8f00cc1fa976d13a9b2538ea73b93308f3327467c0fc49b574886e3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.10.18

Security for ghost-blog-smart 1.1.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page