daily-journal-prompt/README.md

# Daily Journal Prompt Generator

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.

## ✨ 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

## 📋 Prerequisites

- Python 3.7+
- An API key from an OpenAI-compatible service (DeepSeek, OpenAI, etc.)
- Basic knowledge of Python and command line usage

## 🚀 Installation & Setup

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
   ```

## 📁 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
├── historic_prompts.json    # History of previous 60 prompts (JSON format)
├── pool_prompts.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
```

### File Descriptions

- **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
- **historic_prompts.json**: JSON array containing the last 60 generated prompts (cyclic buffer)
- **pool_prompts.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

## 🎯 Quick Start

### Using the Bash Script (Recommended)
```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
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

### 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

```bash
# Default: Draw prompts from pool (no API call)
python generate_prompts.py

# Interactive mode with menu
python generate_prompts.py --interactive

# 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
```

### Interactive Mode Options

1. **Draw prompts from pool (no API call)**: Displays 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 `historic_prompts.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 `historic_prompts.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 `historic_prompts.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

### Environment Variables

Create a `.env` file with your API configuration:

```env
# For DeepSeek
DEEPSEEK_API_KEY="sk-your-deepseek-api-key"

# For OpenAI
# OPENAI_API_KEY="sk-your-openai-api-key"

# Optional: Custom API base URL
# API_BASE_URL="https://api.deepseek.com"
```

### Prompt Template Customization

You can modify `ds_prompt.txt` to change the prompt generation parameters:

- Number of prompts generated (default: 6)
- Prompt length requirements (default: 500-1000 characters)
- Specific themes or constraints
- Output format specifications

## 🔄 Maintaining Prompt History

The `historic_prompts.json` file maintains a rolling history of the last 60 prompts. This helps:

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

## 🤝 Contributing

Contributions are welcome! Here are some ways you can contribute:

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

## 📄 License

[Add appropriate license information here]

## 🙏 Acknowledgments

- Inspired by the need for consistent journaling practice
- Built with OpenAI-compatible AI services
- Community contributions welcome

## 🆘 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