working baseline

README.md

@@ -25,7 +25,19 @@ A Python tool that uses OpenAI-compatible AI endpoints to generate creative writ
    cd daily-journal-prompt
    ```
 
-2. **Set up environment variables**:
+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
    ```
@@ -39,9 +51,9 @@ A Python tool that uses OpenAI-compatible AI endpoints to generate creative writ
    # OPENAI_API_KEY="sk-your-openai-api-key"
    ```
 
-3. **Install required Python packages**:
+4. **Install required Python packages**:
    ```bash
-   pip install openai python-dotenv
+   pip install -r requirements.txt
    ```
 
 ## 📁 Project Structure
@@ -49,6 +61,11 @@ A Python tool that uses OpenAI-compatible AI endpoints to generate creative writ
 ```
 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
 ├── historic_prompts.json    # History of previous 60 prompts (JSON format)
 ├── example.env              # Example environment configuration
@@ -58,26 +75,68 @@ daily-journal-prompt/
 
 ### File Descriptions
 
-- **ds_prompt.txt**: The core prompt template that instructs the AI to generate 6 new journal prompts while avoiding repetition with the last 60 prompts.
-- **historic_prompts.json**: A JSON array containing the last 60 generated prompts. This file is updated each time new prompts are generated.
-- **example.env**: Template for your environment configuration. Copy this to `.env` and add your API key.
-- **.env**: Your actual environment variables (not tracked in git for security).
+- **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 6 new journal prompts
+- **historic_prompts.json**: JSON array containing the last 60 generated prompts
+- **example.env**: Template for your environment configuration
+- **.env**: Your actual environment variables (not tracked in git for security)
 
-## 🔧 Implementation Status
+## 🎯 Quick Start
 
-This repository currently provides:
-- ✅ Complete prompt template for AI interaction
-- ✅ Historic prompt database with 60 example prompts
-- ✅ Environment configuration template
-- ✅ Comprehensive documentation
+### Using the Bash Script (Recommended)
+```bash
+# Make the script executable
+chmod +x run.sh
 
-**To complete the implementation**, you need to:
-1. Create a Python script (see example above)
-2. Add API key parsing and AI client initialization
-3. Implement prompt parsing and history management
-4. Add error handling and user interface
+# Generate prompts (default)
+./run.sh
 
-The example Python code in the "Getting Started" section provides a complete starting point.
+# 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
+pip install -r requirements.txt
+
+# Generate prompts (default)
+python generate_prompts.py
+
+# Interactive mode
+python generate_prompts.py --interactive
+
+# Show statistics
+python generate_prompts.py --stats
+
+# Simple version (no rich dependency needed)
+python simple_generate.py
+```
+
+### Testing Your Setup
+```bash
+# Run the test suite
+python test_project.py
+```
 
 ## 🔧 Usage
 
@@ -85,10 +144,10 @@ The example Python code in the "Getting Started" section provides a complete sta
 ### Prompt Generation Process
 
 1. The system reads the template from `ds_prompt.txt`
-2. It loads the previous 60 prompts from `historic_prompts.json`
+2. It loads the previous 60 prompts from the fixed length cyclic buffer `historic_prompts.json`
 3. The AI generates 6 new prompts, attempting to minimize repetition
-4. New prompts are added to the history (maintaining only the last 60)
-5. User selects one prompt for their journal writing session
+4. Six new prompts are offered (maintaining only the last 60)
+5. User selects one prompt for their journal writing session, which is added to the `historic_prompts.json` cyclic buffer.
 
 ## 📝 Prompt Examples