From e62b342936954bd84c9808f041e84237727922c7 Mon Sep 17 00:00:00 2001 From: Tim Dickey <80638631+tim-dickey@users.noreply.github.com> Date: Fri, 19 Dec 2025 19:23:49 -0600 Subject: [PATCH 1/2] Add MIT License --- LICENSE | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) create mode 100644 LICENSE diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..6c3dfae --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +# MIT License + +Copyright (c) 2025 Tim Dickey + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. From 1a09c4614581dbeb96cee40c8d7a25c6bfffa072 Mon Sep 17 00:00:00 2001 From: Tim Dickey <80638631+tim-dickey@users.noreply.github.com> Date: Fri, 19 Dec 2025 19:24:23 -0600 Subject: [PATCH 2/2] Add comprehensive setup guide --- SETUP.md | 226 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 226 insertions(+) create mode 100644 SETUP.md diff --git a/SETUP.md b/SETUP.md new file mode 100644 index 0000000..784e3b4 --- /dev/null +++ b/SETUP.md @@ -0,0 +1,226 @@ +# TrendResponse Setup Guide + +This guide walks you through setting up the TrendResponse project from scratch. + +## Prerequisites + +1. **Python 3.11 or higher** + ```bash + python --version # Should be 3.11+ + ``` + +2. **GitHub Personal Access Token** + - Go to https://github.com/settings/tokens + - Click "Generate new token (classic)" + - Select scopes: `repo`, `read:org` + - Copy the token (starts with `ghp_`) + +3. **LinkedIn Developer Account** (for LinkedIn integration) + - Go to https://www.linkedin.com/developers/ + - Create a new app + - Note your Client ID and Client Secret + - Add redirect URI: `http://localhost:8000/auth/linkedin/callback` + +## Quick Start + +### 1. Clone and Setup + +```bash +# Clone repository +git clone https://github.com/tim-dickey/trendresponse.git +cd trendresponse + +# Create virtual environment +python -m venv venv + +# Activate virtual environment +# On Windows: +venv\Scripts\activate +# On macOS/Linux: +source venv/bin/activate + +# Install dependencies +pip install -r requirements.txt +``` + +### 2. Configure Environment + +```bash +# Copy example environment file +cp .env.example .env + +# Edit .env with your credentials +# Required: +# - GITHUB_TOKEN: Your GitHub PAT +# - LINKEDIN_CLIENT_ID: From LinkedIn Developer Portal +# - LINKEDIN_CLIENT_SECRET: From LinkedIn Developer Portal +# - SECRET_KEY: Generate with: python -c "import secrets; print(secrets.token_hex(32))" +``` + +### 3. Run the Application + +```bash +# Start the server +uvicorn src.main:app --reload --host 0.0.0.0 --port 8000 + +# Access API docs at: http://localhost:8000/docs +``` + +## Docker Setup (Recommended) + +### 1. Using Docker Compose + +```bash +# Create .env file (same as above) +cp .env.example .env +# Edit .env with your credentials + +# Start all services (API, PostgreSQL, Redis) +docker-compose up -d + +# View logs +docker-compose logs -f api + +# Stop services +docker-compose down +``` + +### 2. Docker Only + +```bash +# Build image +docker build -t trendresponse:latest . + +# Run container +docker run -d \ + -p 8000:8000 \ + -e GITHUB_TOKEN=your_token \ + -e LINKEDIN_CLIENT_ID=your_client_id \ + -e LINKEDIN_CLIENT_SECRET=your_secret \ + -e SECRET_KEY=your_secret_key \ + trendresponse:latest +``` + +## Testing AI Suggestions + +Once the server is running, you can test the AI suggestion feature: + +```bash +# First, you need an auth token (temporary workaround for MVP) +# The full OAuth flow is still being implemented + +# Test comment validation +curl -X POST "http://localhost:8000/comments/validate" \ + -H "Content-Type: application/json" \ + -d '{"content": "This is a test comment with exactly ten words here"}' + +# Expected response: +# {"valid": true, "word_count": 10, "message": "Comment is valid"} +``` + +## Development Workflow + +### Running Tests + +```bash +# Run all tests +pytest + +# Run with coverage +pytest --cov=src --cov-report=html + +# Run specific test file +pytest tests/test_suggestions.py -v + +# Run and show print statements +pytest -s tests/ +``` + +### Code Quality + +```bash +# Format code +black src/ tests/ + +# Sort imports +isort src/ tests/ + +# Lint +ruff check src/ tests/ + +# Run all quality checks +black src/ tests/ && isort src/ tests/ && ruff check src/ tests/ +``` + +## GitHub Models Setup + +The application uses **GitHub Models** (free tier) for AI-powered suggestions: + +1. **GitHub Token Requirements:** + - Your GitHub PAT needs `repo` scope + - Free tier includes: 15 requests/minute, 150 requests/hour + - Upgrade to paid for higher limits + +2. **Available Models:** + - Default: `openai/gpt-4.1-mini` (fast, cost-effective) + - Alternatives: `openai/gpt-4.1`, `openai/o1-mini` + - Change via `MODEL_NAME` in `.env` + +3. **Test the Model:** + ```bash + # Test API access + curl https://models.github.ai/inference/chat/completions \ + -H "Authorization: Bearer $GITHUB_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "model": "openai/gpt-4.1-mini", + "messages": [{"role": "user", "content": "Hello!"}] + }' + ``` + +## Troubleshooting + +### Issue: "Could not validate credentials" +- **Solution**: Generate a new SECRET_KEY or check your .env file is loaded + +### Issue: "GitHub API rate limit exceeded" +- **Solution**: Wait for rate limit reset or upgrade GitHub subscription + +### Issue: Database errors +- **Solution**: Delete `trendresponse.db` and restart (dev only) + +### Issue: Docker container won't start +- **Solution**: Check logs with `docker-compose logs api` +- Verify all environment variables are set + +## Next Steps + +1. **Explore API Documentation** + - Open http://localhost:8000/docs in your browser + - Try the interactive Swagger UI + +2. **Set Up LinkedIn OAuth** + - Complete LinkedIn app configuration + - Test the OAuth flow at `/auth/linkedin/callback` + +3. **Add Sample Data** + - Seed the database with sample posts for testing + - See `scripts/seed_data.py` (to be created) + +4. **Deploy to Production** + - See deployment guides in `docs/deployment/` + - Options: AWS Lambda, Heroku, Azure Container Apps + +## Additional Resources + +- **API Documentation**: http://localhost:8000/docs +- **GitHub Models**: https://github.com/marketplace/models +- **FastAPI Docs**: https://fastapi.tiangolo.com/ +- **LinkedIn API**: https://learn.microsoft.com/en-us/linkedin/ + +## Support + +For issues or questions: +- Open an issue on GitHub +- Check existing issues for solutions +- Review the comprehensive README.md