TrendResponse

AI-Powered Social Media Rapid-Response Platform

Engage on trending posts with concise, AI-suggested comments in seconds

🚀 Overview

TrendResponse helps professionals maintain social media presence without the time investment. Powered by GitHub AI models, it generates concise, thoughtful 10-25 word comments on trending posts, reducing composition time by 80%.

Key Features

🤖 AI-Powered Suggestions: Generate 3-5 contextual comment options using GPT-4.1-mini
⚡ Rapid Composition: Create comments in <30 seconds vs 3-5 minutes manually
📏 Constraint Enforcement: Automatic 10-25 word validation for concise engagement
🔄 Multi-Platform Ready: Modular architecture supporting LinkedIn, Twitter, and more
💰 Cost-Effective: Free tier with GitHub Models, scales affordably
🐳 Containerized: Docker-ready for cloud-agnostic deployment

📋 Prerequisites

Python 3.11+
Docker & Docker Compose (optional, for containerized deployment)
GitHub Personal Access Token (for free AI model access)
LinkedIn OAuth Credentials (for LinkedIn integration)

🛠️ Quick Start

1. Clone the Repository

git clone https://github.com/tim-dickey/trendresponse.git
cd trendresponse

2. Set Up Environment

# Copy environment template
cp .env.example .env

# Edit .env with your credentials:
# - GITHUB_TOKEN: Your GitHub Personal Access Token (https://github.com/settings/tokens)
# - LINKEDIN_CLIENT_ID & SECRET: From LinkedIn Developer Portal
# - SECRET_KEY: Generate with: openssl rand -hex 32

3. Install Dependencies

Option A: Local Development

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Download spaCy model (optional, for NLP features)
python -m spacy download en_core_web_sm

Option B: Docker (Recommended)

docker-compose up -d

4. Run the Application

Local:

uvicorn src.main:app --reload --host 0.0.0.0 --port 8000

Docker:

docker-compose up

5. Access the API

API Documentation: http://localhost:8000/docs (Swagger UI)
Alternative Docs: http://localhost:8000/redoc (ReDoc)
Health Check: http://localhost:8000/health

🎯 Usage

Generate Comment Suggestions

curl -X POST "http://localhost:8000/comments/suggest" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "post_id": "linkedin-post-123",
    "num_suggestions": 3
  }'

Response:

{
  "suggestions": [
    "Fascinating perspective on remote work dynamics. How do you balance async communication with team cohesion?",
    "This aligns with recent studies showing productivity gains. Have you measured impact on employee satisfaction?",
    "Great insights! We've seen similar patterns. What tools do you recommend for distributed collaboration?"
  ]
}

Validate Comment

curl -X POST "http://localhost:8000/comments/validate" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "This is a test comment with exactly fifteen words in total for validation purposes."
  }'

Post Comment

curl -X POST "http://localhost:8000/comments/post" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "post_id": "linkedin-post-123",
    "content": "Insightful analysis! How do you see this evolving with emerging AI capabilities?",
    "platform": "linkedin"
  }'

🏗️ Architecture

┌─────────────────────────────────────────────────────┐
│ Presentation Layer (FastAPI + Swagger UI)           │
│ - Dashboard: Trending posts feed                    │
│ - Composer: Constrained input (10-25 words)         │
│ - Suggestions: AI-powered recommendations           │
└──────────────────┬──────────────────────────────────┘
                   │
┌──────────────────▼──────────────────────────────────┐
│ Logic Layer (Python Backend)                        │
│ - Feed aggregation (LinkedIn, Twitter, etc.)        │
│ - AI suggestion engine (GitHub Models)              │
│ - Word count validation & optimization              │
│ - User authentication & preferences                 │
└──────────────────┬──────────────────────────────────┘
                   │
┌──────────────────▼──────────────────────────────────┐
│ Data & Integration Layer                            │
│ - Platform adapters (LinkedIn API, Twitter API)     │
│ - Database (SQLite → PostgreSQL)                    │
│ - Cache (Redis, optional)                           │
└─────────────────────────────────────────────────────┘

Tech Stack

Component	Technology	Purpose
Framework	FastAPI	Modern, async-first web framework
AI Models	GitHub Models (GPT-4.1-mini)	Free-tier AI with Azure AI Inference SDK
Database	SQLite → PostgreSQL	SQLite for dev, PostgreSQL for production
Auth	OAuth 2.0	Platform-native authentication
Cache	Redis (optional)	Session management & rate limiting
Containers	Docker + Docker Compose	Reproducible, cloud-agnostic deployment
Testing	pytest + pytest-asyncio	Unit, integration, and E2E tests

🧪 Testing

# Run all tests with coverage
pytest --cov=src --cov-report=html

# Run specific test file
pytest tests/test_suggestions.py -v

# Run with live output
pytest -s tests/

Test Coverage Goals:

Unit tests: 70%+ coverage
Integration tests: All API endpoints
Performance tests: <2s p95 latency

🚢 Deployment

Docker (Recommended)

# Build and run
docker-compose up -d --build

# View logs
docker-compose logs -f api

# Stop services
docker-compose down

Cloud Deployment

AWS Lambda + API Gateway:

# Install Mangum for AWS Lambda
pip install mangum

# Deploy with AWS SAM or Serverless Framework
# See docs/deployment/aws-lambda.md

Heroku:

heroku create trendresponse-api
heroku addons:create heroku-postgresql:hobby-dev
git push heroku main

Azure Container Apps:

az containerapp up \
  --name trendresponse \
  --resource-group myResourceGroup \
  --image trendresponse:latest \
  --target-port 8000

📖 API Documentation

Authentication Endpoints

Method	Endpoint	Description
POST	`/auth/linkedin/callback`	LinkedIn OAuth callback
POST	`/auth/logout`	Logout user
GET	`/auth/status`	Check auth status

Feed Endpoints

Method	Endpoint	Description
GET	`/feed/trending`	Get trending posts (limit=50)
GET	`/feed/posts/{post_id}`	Get full post details

Comment Endpoints

Method	Endpoint	Description
POST	`/comments/validate`	Validate word count
POST	`/comments/suggest`	Generate AI suggestions
POST	`/comments/post`	Post comment to platform
GET	`/comments/history`	Get user's comment history

User Endpoints

Method	Endpoint	Description
GET	`/user/profile`	Get user profile
GET	`/user/preferences`	Get user preferences
PUT	`/user/preferences`	Update preferences

🔧 Configuration

Environment Variables

# Database
DATABASE_URL=sqlite+aiosqlite:///./trendresponse.db

# AI Models (GitHub Models - Free Tier)
GITHUB_TOKEN=ghp_your_token_here
MODEL_ENDPOINT=https://models.github.ai/inference/
MODEL_NAME=openai/gpt-4.1-mini

# LinkedIn OAuth
LINKEDIN_CLIENT_ID=your_client_id
LINKEDIN_CLIENT_SECRET=your_client_secret

# Security
SECRET_KEY=your-secret-key-change-in-production

# Comment Constraints
MIN_WORD_COUNT=10
MAX_WORD_COUNT=25

🗺️ Roadmap

v0.1 - MVP ✅ (Current)

User authentication (LinkedIn OAuth stub)
AI-powered comment suggestions (GitHub Models)
Word count validation (10-25 words)
Basic API endpoints
Docker containerization

v0.2 - Enhancement (Weeks 5-8)

v1.0 - Multi-Platform (Weeks 9-12)

v1.5+ - Scale & Optimize

Native iOS/Android apps
Mastodon, Bluesky support
Engagement analytics dashboard
Enterprise tier (audit logs, team management)

🤝 Contributing

Contributions are welcome! Please follow these guidelines:

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Commit changes: git commit -m 'feat: add amazing feature'
Push to branch: git push origin feature/amazing-feature
Open a Pull Request

Development Standards

Code style: Black (line length: 100), isort, ruff
Testing: pytest with 70%+ coverage
Commits: Conventional Commits format
Documentation: Docstrings for all public functions

📄 License

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

🙏 Acknowledgments

GitHub Models: Free AI model access for rapid development
FastAPI: Modern, fast web framework for Python
Azure AI Inference SDK: Seamless integration with GitHub models
LinkedIn & Twitter: Social media platforms enabling engagement

📧 Contact

Tim Dickey - @tim-dickey

Project Link: https://github.com/tim-dickey/trendresponse

Built with ❤️ using GitHub Models and FastAPI

Name		Name	Last commit message	Last commit date
Latest commit History 10 Commits
src		src
tests		tests
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
SETUP.md		SETUP.md
docker-compose.yml		docker-compose.yml
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt

License

tim-dickey/trendresponse

Folders and files

Latest commit

History

Repository files navigation