README.md

---
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](https://docs.astral.sh/uv/) installed
- **Node.js 18+** 
- **pnpm** (recommended) or npm
- **OpenAI API Key** - Get one from [OpenAI Platform](https://platform.openai.com/account/api-keys)

### 1. Environment Setup

Create a `.env` file in the project root:
```bash
OPENAI_API_KEY=sk-your-actual-openai-api-key-here
```

### 2. Backend Setup

```bash
# 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

```bash
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)
```bash
# 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:
```bash
# 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:**
```bash
uv sync                    # Install dependencies
uv run uvicorn backend.main:app --reload  # Start server
```

**Frontend:**
```bash
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

```bash
# 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.