Hugging Face's logo

Spaces:
richlai
/
AI-Newsletter
Sleeping

App Files Community
AI-Newsletter / README.md
Richard Lai
config
fc18788
preview code
|
raw
history blame contribute delete
8.08 kB
metadata
title: AI Newsletter Generator
emoji: 📰
colorFrom: indigo
colorTo: purple
sdk: docker
app_file: app.py
pinned: false

AI Newsletter Generator

A full-stack AI-powered newsletter generator that creates engaging newsletters from RSS feeds with intelligent article summarization, tweet generation, and AI-assisted editing.

✨ Features

  • 🤖 AI-Enhanced Article Summaries: LLM-generated engaging abstracts for better readability
  • 📰 RSS Feed Aggregation: Curate content from multiple AI/tech news sources
  • 🔍 Smart Article Selection: Interactive interface to choose articles for processing
  • 📝 Deep Article Summarization: AI-powered detailed summaries of selected articles
  • 🐦 Social Media Content: Generate Twitter/X posts with AI editing capabilities
  • 📧 Professional Newsletters: Create polished HTML newsletters
  • ✨ Interactive AI Editing: Real-time AI assistance for content refinement
  • 🎨 Modern UI: Beautiful React interface with gradient backgrounds and smooth interactions
  • ⚡ Fast Performance: Vite-powered frontend with hot reload
  • 🔒 Environment Security: Secure API key management

🏗️ Architecture

Project Structure 

AI-NewsLetter/
├── backend/                 # FastAPI backend
│   └── main.py             # API endpoints + static file serving
├── frontend/               # React + Vite + Tailwind frontend
│   ├── src/
│   │   ├── components/     # React components
│   │   │   ├── FeedPicker.tsx
│   │   │   ├── TweetCards.tsx
│   │   │   └── EditorModal.tsx
│   │   ├── App.tsx         # Main application
│   │   └── index.css       # Tailwind styles
│   └── dist/               # Built frontend (served by backend)
├── pyproject.toml          # Python dependencies (managed by uv)
├── .env                    # Environment variables
└── README.md

Technology Stack

Backend:

  • FastAPI - Modern Python web framework with automatic API docs
  • OpenAI API - GPT-4o-mini for content generation and enhancement
  • httpx - Async HTTP client for web scraping
  • feedparser - RSS/Atom feed parsing
  • uvicorn - High-performance ASGI server

Frontend:

  • React 19 - Latest React with modern hooks
  • TypeScript - Type safety and better developer experience
  • Vite - Lightning-fast build tool and dev server
  • Tailwind CSS v3 - Utility-first styling with custom components
  • pnpm - Fast, disk-efficient package manager

Development Tools:

  • uv - Ultra-fast Python package manager
  • ESLint - Code linting and formatting
  • PostCSS - CSS processing with Tailwind

🚀 Quick Start

Prerequisites

  • Python 3.12+ with uv installed
  • Node.js 18+
  • pnpm (recommended) or npm
  • OpenAI API Key - Get one from OpenAI Platform

1. Environment Setup

Create a .env file in the project root:

OPENAI_API_KEY=sk-your-actual-openai-api-key-here

2. Backend Setup 

# Install Python dependencies
uv sync

# Start the FastAPI server (serves both API and frontend)
uv run uvicorn backend.main:app --host 127.0.0.1 --port 8000 --reload

3. Frontend Setup 

cd frontend

# Install dependencies
pnpm install

# Build for production
pnpm build

4. Access the Application

Open your browser to http://127.0.0.1:8000

The backend serves both the API endpoints and the built React frontend from a single port.

📖 User Guide

Workflow

  1. Select Sources: Choose from curated AI/tech RSS feeds
  2. Get Highlights: Fetch articles and generate initial AI summary
  3. Select Articles: Review articles with AI-enhanced abstracts
  4. Get Summaries: Generate detailed summaries for selected articles (max 5)
  5. Generate Tweets: Create social media content with AI editing
  6. Create Newsletter: Build professional HTML newsletter
  7. Download: Export your newsletter

Key Features Explained

AI-Enhanced Abstracts: When you click "Get Highlights", the system not only fetches articles but uses GPT to create engaging 2-3 sentence summaries for each article, making them much more readable and compelling than raw RSS descriptions.

Smart Article Selection: The interface shows checkboxes for each article with enhanced summaries, publication dates, and sources. You can easily select which articles to dive deeper into.

Detailed Summarization: The "Get Summaries" feature scrapes full article content and creates comprehensive summaries using AI, perfect for busy readers who want key insights.

Interactive AI Editing: Both tweets and newsletter content can be edited with AI assistance through natural language commands.

🔧 Development

Full-Stack Development (Recommended) 

# Terminal 1: Start backend
uv run uvicorn backend.main:app --host 127.0.0.1 --port 8000 --reload

# Terminal 2: Build frontend after changes
cd frontend && pnpm build

Frontend-Only Development

For rapid UI development with hot reload:

# Terminal 1: Backend
uv run uvicorn backend.main:app --host 127.0.0.1 --port 8000 --reload

# Terminal 2: Frontend dev server
cd frontend && pnpm dev --port 3002

Then open http://127.0.0.1:3002 for development or http://127.0.0.1:8000 for production.

Available Scripts

Backend:

uv sync                    # Install dependencies
uv run uvicorn backend.main:app --reload  # Start server

Frontend:

pnpm install              # Install dependencies
pnpm build                # Build for production
pnpm dev                  # Development server
pnpm type-check           # TypeScript checking
pnpm clean                # Clean build artifacts

🌐 API Reference

Core Endpoints

  • GET / - Serves React frontend application
  • GET /api/health - API health check
  • GET /api/defaults - Get default RSS feed sources

Content Generation

  • POST /api/aggregate - Fetch articles from RSS feeds with AI-enhanced summaries
  • POST /api/highlights - Generate weekly highlights summary
  • POST /api/summaries_selected - Create detailed summaries for selected articles
  • POST /api/tweets - Generate social media posts from summaries
  • POST /api/newsletter - Create HTML newsletter
  • POST /api/edit_tweet - AI-powered tweet editing

Example API Usage 

# Get enhanced articles with AI summaries
curl -X POST "http://127.0.0.1:8000/api/aggregate" \
  -H "Content-Type: application/json" \
  -d '{"sources": ["https://huggingface.co/blog/feed.xml"]}'

# Generate detailed summaries
curl -X POST "http://127.0.0.1:8000/api/summaries_selected" \
  -H "Content-Type: application/json" \
  -d '{"articles": [...]}'

🐳 Deployment

Hugging Face Spaces

This project includes a Dockerfile optimized for Hugging Face Spaces deployment:

  1. Push your code to a Hugging Face repository
  2. Set your OPENAI_API_KEY in the Space settings
  3. The Dockerfile will handle the rest!

Other Platforms

The application can be deployed on any platform that supports Docker containers:

  • Railway
  • Render
  • DigitalOcean App Platform
  • AWS ECS
  • Google Cloud Run

🤝 Contributing

Contributions are welcome! This project uses:

  • Python: Black formatting, type hints encouraged
  • TypeScript: Strict mode, ESLint configuration
  • Git: Conventional commit messages preferred

📄 License

This project is open source and available under the MIT License.

🙋‍♂️ Support

Having issues?

  1. Check that your OpenAI API key is correctly set in .env
  2. Ensure all dependencies are installed (uv sync and pnpm install)
  3. Verify the frontend is built (pnpm build) before accessing the full-stack app

Built with ❤️ using modern web technologies and AI.