non-building checkpoint 1

2026-01-03 11:18:56 -07:00
parent 9c64cb0c2f
commit 81ea22eae9
37 changed files with 4804 additions and 275 deletions
--- a/README.md
+++ b/README.md
@@ -1,268 +1,320 @@
-# Daily Journal Prompt Generator
+# Daily Journal Prompt Generator - Web Application

-A Python tool that uses OpenAI-compatible AI endpoints to generate creative writing prompts for daily journaling. The tool maintains awareness of previous prompts to minimize repetition while providing diverse, thought-provoking topics for journal writing.
+A modern web application for generating AI-powered journal writing prompts, refactored from a CLI tool to a full web stack with FastAPI backend and Astro frontend.

 ## ✨ Features

- **AI-Powered Prompt Generation**: Uses OpenAI-compatible APIs to generate creative writing prompts
- **Smart Repetition Avoidance**: Maintains history of the last 60 prompts to minimize thematic overlap
- **Multiple Options**: Generates 6 different prompt options for each session
- **Diverse Topics**: Covers a wide range of themes including memories, creativity, self-reflection, and imagination
- **Simple Configuration**: Easy setup with environment variables for API keys
- **JSON-Based History**: Stores prompt history in a structured JSON format for easy management
+- **AI-Powered Prompt Generation**: Uses DeepSeek/OpenAI API to generate creative writing prompts
+- **Smart History System**: 60-prompt cyclic buffer to avoid repetition and steer themes
+- **Prompt Pool Management**: Caches prompts for offline use with automatic refilling
+- **Theme Feedback System**: AI analyzes your preferences to improve future prompts
+- **Modern Web Interface**: Responsive design with intuitive UI
+- **RESTful API**: Fully documented API for programmatic access
+- **Docker Support**: Easy deployment with Docker and Docker Compose

-## 📋 Prerequisites
+## 🏗️ Architecture

- Python 3.7+
- An API key from an OpenAI-compatible service (DeepSeek, OpenAI, etc.)
- Basic knowledge of Python and command line usage
+### Backend (FastAPI)
+- **Framework**: FastAPI with async/await support
+- **API Documentation**: Automatic OpenAPI/Swagger documentation
+- **Data Persistence**: JSON file storage with async file operations
+- **Services**: Modular architecture with clear separation of concerns
+- **Validation**: Pydantic models for request/response validation
+- **Error Handling**: Comprehensive error handling with custom exceptions

-## 🚀 Installation & Setup
+### Frontend (Astro + React)
+- **Framework**: Astro with React components for interactivity
+- **Styling**: Custom CSS with modern design system
+- **Responsive Design**: Mobile-first responsive layout
+- **API Integration**: Proxy configuration for seamless backend communication
+- **Component Architecture**: Reusable React components

-1. **Clone the repository**:
-   ```bash
-   git clone <repository-url>
-   cd daily-journal-prompt
-   ```
-
-2. **Set up a Python virtual environment (recommended)**:
-   ```bash
-   # Create a virtual environment
-   python -m venv venv
-
-   # Activate the virtual environment
-   # On Linux/macOS:
-   source venv/bin/activate
-   # On Windows:
-   # venv\Scripts\activate
-   ```
-
-3. **Set up environment variables**:
-   ```bash
-   cp example.env .env
-   ```
-
-   Edit the `.env` file and add your API key:
-   ```env
-   # DeepSeek
-   DEEPSEEK_API_KEY="sk-your-actual-api-key-here"
-
-   # Or for OpenAI
-   # OPENAI_API_KEY="sk-your-openai-api-key"
-   ```
-
-4. **Install required Python packages**:
-   ```bash
-   pip install -r requirements.txt
-   ```
+### Infrastructure
+- **Docker**: Multi-container setup with development and production configurations
+- **Docker Compose**: Orchestration for local development
+- **Nginx**: Reverse proxy for frontend serving
+- **Health Checks**: Container health monitoring

 ## 📁 Project Structure

 ```
 daily-journal-prompt/
-├── README.md                 # This documentation
-├── generate_prompts.py      # Main Python script with rich interface
-├── simple_generate.py       # Lightweight version without rich dependency
-├── run.sh                   # Convenience bash script
-├── test_project.py          # Test suite for the project
-├── requirements.txt         # Python dependencies
-├── ds_prompt.txt            # AI prompt template for generating journal prompts
-├── prompts_historic.json    # History of previous 60 prompts (JSON format)
-├── prompts_pool.json        # Pool of available prompts for selection (JSON format)
-├── example.env              # Example environment configuration
-├── .env                     # Your actual environment configuration (gitignored)
-├── settings.cfg            # Configuration file for prompt settings and pool size
-└── .gitignore              # Git ignore rules
+├── backend/                    # FastAPI backend
+│   ├── app/
+│   │   ├── api/v1/            # API endpoints
+│   │   ├── core/              # Configuration, logging, exceptions
+│   │   ├── models/            # Pydantic models
+│   │   └── services/          # Business logic services
+│   ├── main.py                # FastAPI application entry point
+│   └── requirements.txt       # Python dependencies
+├── frontend/                  # Astro frontend
+│   ├── src/
+│   │   ├── components/        # React components
+│   │   ├── layouts/           # Layout components
+│   │   ├── pages/             # Astro pages
+│   │   └── styles/            # CSS styles
+│   ├── astro.config.mjs       # Astro configuration
+│   └── package.json           # Node.js dependencies
+├── data/                      # Data storage (mounted volume)
+│   ├── prompts_historic.json  # Historic prompts
+│   ├── prompts_pool.json      # Prompt pool
+│   ├── feedback_words.json    # Feedback words with weights
+│   ├── feedback_historic.json # Historic feedback
+│   ├── ds_prompt.txt          # Prompt template
+│   ├── ds_feedback.txt        # Feedback template
+│   └── settings.cfg           # Application settings
+├── docker-compose.yml         # Docker Compose configuration
+├── backend/Dockerfile         # Backend Dockerfile
+├── frontend/Dockerfile        # Frontend Dockerfile
+├── .env.example              # Environment variables template
+├── API_DOCUMENTATION.md      # API documentation
+├── AGENTS.md                 # Project planning and architecture
+└── README.md                 # This file
 ```

-### File Descriptions
+## 🚀 Quick Start

- **generate_prompts.py**: Main Python script with interactive mode, rich formatting, and full features
- **simple_generate.py**: Lightweight version without rich dependency for basic usage
- **run.sh**: Convenience bash script for easy execution
- **test_project.py**: Test suite to verify project setup
- **requirements.txt**: Python dependencies (openai, python-dotenv, rich)
- **ds_prompt.txt**: The core prompt template that instructs the AI to generate new journal prompts
- **prompts_historic.json**: JSON array containing the last 60 generated prompts (cyclic buffer)
- **prompts_pool.json**: JSON array containing the pool of available prompts for selection
- **example.env**: Template for your environment configuration
- **.env**: Your actual environment variables (not tracked in git for security)
- **settings.cfg**: Configuration file for prompt settings (length, count) and pool size
+### Prerequisites
+- Python 3.11+
+- Node.js 18+
+- Docker and Docker Compose (optional)
+- API key from DeepSeek or OpenAI

-## 🎯 Quick Start
+### Option 1: Docker (Recommended)

-### Using the Bash Script (Recommended)
+1. **Clone and setup**
+   ```bash
+   git clone <repository-url>
+   cd daily-journal-prompt
+   cp .env.example .env
+   ```
+
+2. **Edit .env file**
+   ```bash
+   # Add your API key
+   DEEPSEEK_API_KEY=your_api_key_here
+   # or
+   OPENAI_API_KEY=your_api_key_here
+   ```
+
+3. **Start with Docker Compose**
+   ```bash
+   docker-compose up --build
+   ```
+
+4. **Access the application**
+   - Frontend: http://localhost:3000
+   - Backend API: http://localhost:8000
+   - API Documentation: http://localhost:8000/docs
+
+### Option 2: Manual Setup
+
+#### Backend Setup
 ```bash
-# Make the script executable
-chmod +x run.sh
-
-# Generate prompts (default)
-./run.sh
-
-# Interactive mode with rich interface
-./run.sh --interactive
-
-# Simple version without rich dependency
-./run.sh --simple
-
-# Show statistics
-./run.sh --stats
-
-# Show help
-./run.sh --help
-```
-
-### Using Python Directly
-```bash
-# First, activate your virtual environment (if using one)
-# On Linux/macOS:
-# source venv/bin/activate
-# On Windows:
-# venv\Scripts\activate
-
-# Install dependencies
+cd backend
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
 pip install -r requirements.txt

-# Generate prompts (default)
-python generate_prompts.py
+# Set environment variables
+export DEEPSEEK_API_KEY=your_api_key_here
+# or
+export OPENAI_API_KEY=your_api_key_here

-# Interactive mode
-python generate_prompts.py --interactive
-
-# Show statistics
-python generate_prompts.py --stats
-
-# Simple version (no rich dependency needed)
-python simple_generate.py
+# Run the backend
+uvicorn main:app --reload
 ```

-### Testing Your Setup
+#### Frontend Setup
 ```bash
-# Run the test suite
-python test_project.py
+cd frontend
+npm install
+npm run dev
 ```

-## 🔧 Usage
+## 📚 API Usage

-### New Pool-Based System
-
-The system now uses a two-step process:
-
-1. **Fill the Prompt Pool**: Generate prompts using AI and add them to the pool
-2. **Draw from Pool**: Select prompts from the pool for journaling sessions
-
-### Command Line Options
+The API provides comprehensive endpoints for prompt management:

+### Basic Operations
 ```bash
-# Default: Draw prompts from pool (no API call)
-python generate_prompts.py
+# Draw prompts from pool
+curl http://localhost:8000/api/v1/prompts/draw

-# Interactive mode with menu
-python generate_prompts.py --interactive
+# Fill prompt pool
+curl -X POST http://localhost:8000/api/v1/prompts/fill-pool

-# Fill the prompt pool using AI (makes API call)
-python generate_prompts.py --fill-pool
-
-# Show pool statistics
-python generate_prompts.py --pool-stats
-
-# Show history statistics
-python generate_prompts.py --stats
-
-# Help
-python generate_prompts.py --help
+# Get statistics
+curl http://localhost:8000/api/v1/prompts/stats
 ```

-### Interactive Mode Options
+### Interactive Documentation
+Access the automatic API documentation at:
+- Swagger UI: http://localhost:8000/docs
+- ReDoc: http://localhost:8000/redoc

-1. **Draw prompts from pool (no API call)**: Displays and consumes prompts from the pool file
-2. **Fill prompt pool using API**: Generates new prompts using AI and adds them to pool
-3. **View pool statistics**: Shows pool size, target size, and available sessions
-4. **View history statistics**: Shows historic prompt count and capacity
-5. **Exit**: Quit the program
-
-### Prompt Generation Process
-
-1. User chooses to fill the prompt pool.
-2. The system reads the template from `ds_prompt.txt`
-3. It loads the previous 60 prompts from the fixed length cyclic buffer `prompts_historic.json`
-4. The AI generates some number of new prompts, attempting to minimize repetition
-5. The new prompts are used to fill the prompt pool to the `settings.cfg` configured value.
-
-### Prompt Selection Process
-
-1. A `settings.cfg` configurable number of prompts are drawn from the prompt pool and displayed to the user.
-2. User selects one prompt for his/her journal writing session, which is added to the `prompts_historic.json` cyclic buffer.
-3. All prompts which were displayed are removed from the prompt pool permanently.
-
-## 📝 Prompt Examples
-
-The tool generates prompts like these (from `prompts_historic.json`):
-
- **Memory-based**: "Describe a memory you have that is tied to a specific smell..."
- **Creative Writing**: "Invent a mythological creature for a modern urban setting..."
- **Self-Reflection**: "Write a dialogue between two aspects of yourself..."
- **Observational**: "Describe your current emotional state as a weather system..."
-
-Each prompt is designed to inspire 1-2 pages of journal writing and ranges from 500-1000 characters.
-
-## ⚙️ Configuration
+## 🔧 Configuration

 ### Environment Variables
-
-Create a `.env` file with your API configuration:
+Create a `.env` file based on `.env.example`:

 ```env
-# For DeepSeek
-DEEPSEEK_API_KEY="sk-your-deepseek-api-key"
+# Required: At least one API key
+DEEPSEEK_API_KEY=your_deepseek_api_key
+OPENAI_API_KEY=your_openai_api_key

-# For OpenAI
-# OPENAI_API_KEY="sk-your-openai-api-key"
-
-# Optional: Custom API base URL
-# API_BASE_URL="https://api.deepseek.com"
+# Optional: Customize behavior
+API_BASE_URL=https://api.deepseek.com
+MODEL=deepseek-chat
+DEBUG=false
+CACHED_POOL_VOLUME=20
+NUM_PROMPTS_PER_SESSION=6
 ```

-### Prompt Template Customization
+### Application Settings
+Edit `data/settings.cfg` to customize:
+- Prompt length constraints
+- Number of prompts per session
+- Pool volume targets

-You can modify `ds_prompt.txt` to change the prompt generation parameters:
+## 🧪 Testing

- Number of prompts generated (default: 6)
- Prompt length requirements (default: 500-1000 characters)
- Specific themes or constraints
- Output format specifications
+Run the backend tests:
+```bash
+python test_backend.py
+```

-## 🔄 Maintaining Prompt History
+## 🐳 Docker Development

-The `prompts_historic.json` file maintains a rolling history of the last 60 prompts. This helps:
+### Development Mode
+```bash
+# Hot reload for both backend and frontend
+docker-compose up --build

-1. **Avoid repetition**: The AI references previous prompts to generate new, diverse topics
-2. **Track usage**: See what types of prompts have been generated
-3. **Quality control**: Monitor the variety and quality of generated prompts
+# View logs
+docker-compose logs -f
+
+# Stop services
+docker-compose down
+```
+
+### Useful Commands
+```bash
+# Rebuild specific service
+docker-compose build backend
+
+# Run single service
+docker-compose up backend
+
+# Execute commands in container
+docker-compose exec backend python -m pytest
+```
+
+## 🔄 Migration from CLI
+
+The web application maintains full compatibility with the original CLI data format:
+
+1. **Data Files**: Existing JSON files are automatically used
+2. **Templates**: Same prompt and feedback templates
+3. **Settings**: Compatible settings.cfg format
+4. **Functionality**: All CLI features available via API
+
+## 📊 Features Comparison
+
+| Feature | CLI Version | Web Version |
+|---------|------------|-------------|
+| Prompt Generation | ✅ | ✅ |
+| Prompt Pool | ✅ | ✅ |
+| History Management | ✅ | ✅ |
+| Theme Feedback | ✅ | ✅ |
+| Web Interface | ❌ | ✅ |
+| REST API | ❌ | ✅ |
+| Docker Support | ❌ | ✅ |
+| Multi-user Ready | ❌ | ✅ (future) |
+| Mobile Responsive | ❌ | ✅ |
+
+## 🛠️ Development
+
+### Backend Development
+```bash
+cd backend
+# Install development dependencies
+pip install -r requirements.txt
+
+# Run with hot reload
+uvicorn main:app --reload --host 0.0.0.0 --port 8000
+
+# Run tests
+python test_backend.py
+```
+
+### Frontend Development
+```bash
+cd frontend
+# Install dependencies
+npm install
+
+# Run development server
+npm run dev
+
+# Build for production
+npm run build
+```
+
+### Code Structure
+- **Backend**: Follows FastAPI best practices with dependency injection
+- **Frontend**: Uses Astro islands architecture with React components
+- **Services**: Async/await pattern for I/O operations
+- **Error Handling**: Comprehensive error handling at all levels

 ## 🤝 Contributing

-Contributions are welcome! Here are some ways you can contribute:
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests if applicable
+5. Submit a pull request

-1. **Add new prompt templates** for different writing styles
-2. **Improve the AI prompt engineering** for better results
-3. **Add support for more AI providers**
-4. **Create a CLI interface** for easier usage
-5. **Add tests** to ensure reliability
+### Development Guidelines
+- Follow PEP 8 for Python code
+- Use TypeScript for React components when possible
+- Write meaningful commit messages
+- Update documentation for new features
+- Add tests for new functionality

 ## 📄 License

-[Add appropriate license information here]
+This project is licensed under the MIT License - see the LICENSE file for details.

 ## 🙏 Acknowledgments

- Inspired by the need for consistent journaling practice
- Built with OpenAI-compatible AI services
- Community contributions welcome
+- Built with [FastAPI](https://fastapi.tiangolo.com/)
+- Frontend with [Astro](https://astro.build/)
+- AI integration with [OpenAI](https://openai.com/) and [DeepSeek](https://www.deepseek.com/)
+- Icons from [Font Awesome](https://fontawesome.com/)

-## 🆘 Support
+## 📞 Support

-For issues, questions, or suggestions:
-1. Check the existing issues on GitHub
-2. Create a new issue with detailed information
-3. Provide examples of problematic prompts or errors
+- **Issues**: Use GitHub Issues for bug reports and feature requests
+- **Documentation**: Check `API_DOCUMENTATION.md` for API details
+- **Examples**: See the test files for usage examples
+
+## 🚀 Deployment
+
+### Cloud Platforms
+- **Render**: One-click deployment with Docker
+- **Railway**: Easy deployment with environment management
+- **Fly.io**: Global deployment with edge computing
+- **AWS/GCP/Azure**: Traditional cloud deployment
+
+### Deployment Steps
+1. Set environment variables
+2. Build Docker images
+3. Configure database (if migrating from JSON)
+4. Set up reverse proxy (nginx/caddy)
+5. Configure SSL certificates
+6. Set up monitoring and logging
+
+---
+
+**Happy Journaling! 📓✨**