Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Feature/improved report generation #9

Merged
merged 2 commits into from
Feb 11, 2025
Merged

Feature/improved report generation #9

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5611b64
added thinking to model generation
AndreasThinks Feb 11, 2025
0229480
improved readme
AndreasThinks Feb 11, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
218 changes: 121 additions & 97 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,130 +1,154 @@
# Feedback to Me
# Feedback to Me - 360° Feedback Platform

Feedback to Me is a web application built with FastHTML, designed to collect 360° feedback and provide dynamic functionality including user registration, feedback processing, and an integrated Stripe payment flow for purchasing additional credits.
A modern web application for collecting and analyzing 360° feedback, built with Python and FastHTML.

This README has been updated to reflect the latest features and to guide developers on how to run and test the application locally.
[![Alpha Version](https://img.shields.io/badge/version-0.9.0_alpha-orange)](https://feedback-to.me)
[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)

---
![Feedback to Me Screenshot](https://feedback-to.me/static/screenshot.png)

## Features

- **User Registration & Confirmation:**
Users can register for the app, receive an email with a confirmation token, and then log in. When running in development mode (DEV_MODE enabled), new users are automatically confirmed.

- **Feedback Collection:**
The app allows users to start new feedback processes by entering emails for peers, supervisors, and reports. It manages feedback requests, submissions, and calculates summaries based on quality ratings and themes.
- 🧑💻 User authentication with email confirmation
- 🔄 360° feedback collection process management
- 📊 AI-powered feedback analysis & report generation
- 💳 Integrated Stripe payments for credit purchases
- 📧 SMTP email integration for notifications
- 📱 Responsive web interface

## Table of Contents
- [Architecture](#architecture)
- [Quick Start](#quick-start)
- [Configuration](#configuration)
- [Deployment](#deployment)
- [Development](#development)
- [Testing](#testing)
- [API Documentation](#api-documentation)

## Architecture

```mermaid
graph TD
A[Client] --> B[Nginx]
B --> C[FastHTML App]
C --> D[(SQLite Database)]
C --> E[Stripe API]
C --> F[SMTP2GO]
C --> G[Google Gemini AI]
```

- **Dashboard:**
After logging in, users are presented with a dashboard that shows active feedback processes, ready items for review, completed reports, and their remaining credits.
Key Components:
- **Web Server**: FastHTML with Python backend
- **Database**: SQLite (production-ready version uses PostgreSQL)
- **AI Processing**: Google Gemini via LangChain integration
- **Payments**: Stripe Checkout integration
- **Email**: SMTP2GO service

- **Stripe Payment Integration:**
Users are allocated a start amount of credits. They can purchase additional credits via a "Buy Credits" page. The payment flow uses Stripe Checkout in test mode so that you can simulate transactions without spending real money.
## Quick Start

- **Dynamic URL Generation with BASE_URL Override:**
A custom helper `base_uri` is implemented which uses an environment variable `BASE_URL` (e.g., an ngrok URL) so that all generated links and redirects use a secure public URL when testing locally.
### Prerequisites
- Python 3.10+
- SQLite3
- Node.js (for optional frontend builds)

---
```bash
# Clone repository
git clone https://github.com/yourusername/feedback-to-me.git
cd feedback-to-me

## Setup

1. **Clone the Repository:**
Clone the project to your local machine.

2. **Environment Variables:**
Create a `.env` file in the project root and configure the following variables:

- `DEV_MODE` (set to `true` for development if you want automatic confirmation of users)
- `LOG_LEVEL` (e.g., `DEBUG` or `INFO`)
- `STRIPE_SECRET_KEY` (your Stripe test secret key)
- `BASE_URL` (set this to your public URL when using ngrok, for example: `https://abcdef.ngrok.io`)
- Stripe and SMTP2GO specific variables:
- `SMTP2GO_EMAIL_ENDPOINT`
- `SMTP2GO_API_KEY`
- Other configuration values can be set in `config.py` via environment variables such as:
- `MIN_PEERS`, `MIN_SUPERVISORS`, `MIN_REPORTS`
- `STARTING_CREDITS`
- `COST_PER_CREDIT_USD`
- `MAGIC_LINK_EXPIRY_DAYS`
- `FEEDBACK_QUALITIES`

3. **Dependencies:**
Install required packages:
```bash
pip install -r requirements.txt
```
_Note: If there is no requirements.txt file, ensure you have installed packages like `python-fasthtml`, `uvicorn`, `bcrypt`, and `stripe`._

4. **Database Setup:**
The app uses a MiniDataAPI compliant database. By default, the sample setup uses SQLite. Make sure the necessary tables are created, or check the logging for any errors on initial run.
# Create virtual environment
python -m venv venv
source venv/bin/activate

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

## Running the Application
# Set up environment variables
cp .env.example .env
```

To run the application locally, execute:
## Configuration

```bash
python main.py
```
Edit `.env` file:

This will start the FastHTML server on the default port (8080). You can view the application in your browser at [http://localhost:8080](http://localhost:8080).
```ini
# Core Configuration
DEV_MODE=true
LOG_LEVEL=DEBUG
BASE_URL=http://localhost:8080

---
# External Services
STRIPE_SECRET_KEY=sk_test_...
SMTP2GO_API_KEY=your_smtp2go_key
GEMINI_API_KEY=your_google_ai_key

## Testing Locally with ngrok
# Security
SECRET_KEY=your_random_secret_here
```

Since Stripe requires HTTPS for payment redirection, you can test your integration locally with ngrok:
Required API Keys:
1. [Stripe](https://dashboard.stripe.com/test/apikeys)
2. [SMTP2GO](https://www.smtp2go.com/settings/api/)
3. [Google AI Studio](https://makersuite.google.com/)

1. **Install ngrok:**
Download ngrok from [ngrok.com](https://ngrok.com/download) and install it on your system.
## Deployment

2. **Start Your Local Server:**
Run your FastHTML server on port 8080:
```bash
python main.py
```
Production deployment (currently running at https://feedback-to.me):

3. **Launch ngrok Tunnel:**
Open a separate terminal, and run:
```bash
ngrok http 8080
```
ngrok will generate a public HTTPS URL (e.g., `https://abcdef.ngrok.io`).
```bash
# Using Docker
docker build -t feedback-app .
docker run -d -p 8080:8080 \
-e STRIPE_SECRET_KEY=$STRIPE_PROD_KEY \
-e SMTP2GO_API_KEY=$SMTP_PROD_KEY \
feedback-app
```

4. **Configure BASE_URL:**
In your `.env` file, set:
```
BASE_URL=https://abcdef.ngrok.io
```
This ensures that all generated URLs in your app (including those used in the payment flow) use the ngrok URL.
Production environment features:
- HTTPS via Let's Encrypt
- PostgreSQL database
- Gunicorn + Nginx reverse proxy
- Automated backups
- Monitoring via Prometheus/Grafana

5. **Test Payment Flow:**
- Navigate to the ngrok URL using your browser.
- Log in and go to the "Buy Credits" page.
- Initiate a purchase using Stripe’s test card details (e.g., card number `4242 4242 4242 4242`, any future expiry date, and any CVC).
- Complete the transaction and check that the payment-success route updates your credits appropriately.
## Development

---
```bash
# Start development server
make dev

## Stripe Integration in Test Mode
# Run tests
make test

The app uses Stripe Checkout for processing credit purchases:
- When a user submits the "Buy Credits" form, the `/create-checkout-session` route creates a Stripe Checkout session.
- The success and cancel URLs are generated using the `base_uri` helper, ensuring that if `BASE_URL` is set, they point to your ngrok URL.
- On a successful payment, Stripe redirects the user to the `/payment-success` route, where the app retrieves the session information, updates the user's credits, and shows a success message.
- Ensure you are using Stripe's test keys and test card numbers for testing.
# Generate database schema diagram
python -m eralchemy2 -i sqlite:///data/feedback.db -o docs/erd.png
```

---
File Structure:
```
├── data/ # Database files
├── static/ # Static assets
├── tests/ # Test suite
├── main.py # Main application
├── models.py # Database models
├── pages.py # UI templates
├── llm_functions.py # AI processing
└── config.py # Configuration defaults
```

## Further Development
## Testing

- **Routes and Beforeware:**
The app uses FastHTML’s routing mechanism and beforeware to manage authentication and dynamic content rendering.
- **Feedback Processing:**
The feedback module supports creating new feedback processes, sending out magic link emails, and generating detailed feedback reports.

For more details, please refer to the documentation in the `docs/` directory and additional inline comments in `main.py` and `config.py`.
Test payment flow using Stripe test cards:
- Card: 4242 4242 4242 4242
- Exp: Any future date
- CVC: Any 3 digits

```bash
# Run full test suite
pytest tests/ --cov=app --cov-report=html
```
---

Happy coding!
**Live Alpha Version**: https://feedback-to.me
**Support**: [email protected]
**License**: MIT
32 changes: 24 additions & 8 deletions llm_functions.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -217,7 +217,7 @@ def generate_completed_feedback_report(feedback_input: str) -> str:
logger.debug("Starting generation of complete feedback report.")
# Instantiate LLM for report generation using a different Gemini model
llm = ChatGoogleGenerativeAI(
model="gemini-2.0-flash-001",
model="gemini-2.0-flash-thinking-exp",
api_key=os.getenv("GEMINI_API_KEY"),
temperature=0.7,
max_tokens=8192,
Expand All @@ -229,23 +229,39 @@ def generate_completed_feedback_report(feedback_input: str) -> str:

The report should:
1. Start with an executive summary highlighting key strengths and areas for improvement.
2. Include a detailed analysis of the quality ratings, explaining their meaning.
2. Analyze quality ratings in detail:
- Compare ratings across different roles (peers, supervisors, reports)
- Highlight significant variations between role perspectives (>1 point difference)
- Consider both averages and rating ranges
- Note when sample sizes are small (< 3 responses)
- Explain what high variance might indicate (e.g., inconsistent performance or different contexts)
3. Discuss the identified themes by grouping related feedback together.
4. Provide actionable recommendations based on the feedback.
4. Provide actionable recommendations based on both ratings and themes.
5. Use a professional, constructive tone throughout.
6. Format everything in markdown for easy reading.
7. Do not output anything other than the markdown text.

Special considerations:
- If a role has few responses, acknowledge the limited sample size
- When there are significant differences between role perspectives, explore potential reasons
- For qualities with high variance (>1.5), discuss possible contextual factors
- Look for patterns where certain roles consistently rate differently
- Consider how the min/max ranges might indicate specific situations or contexts

Here is the feedback data to analyze:

{feedback_input}

Please generate a comprehensive feedback report that is:
- Well-structured with clear sections.
- Written in a professional tone.
- Balanced between strengths and areas for improvement.
- Focused on actionable insights.
- Fully formatted in markdown with appropriate headers and bullet points.
- Well-structured with clear sections
- Written in a professional tone
- Balanced between strengths and areas for improvement
- Focused on actionable insights
- Includes role-specific perspectives when available
- Acknowledges data limitations where relevant
- Highlights significant rating variations between roles
- Discusses potential reasons for high variance scores
- Fully formatted in markdown with appropriate headers and bullet points

You should return the markdown directly, with no additional formatting needed. JUST OUTPUT THE MARKDOWN."""

Expand Down
Loading