starting line for feedback implementation

2026-01-03 18:02:31 -07:00
parent 7b98075b7a
commit 01be68c5da
1 changed files with 174 additions and 1 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -848,4 +848,177 @@ All three UI tweaks have been successfully implemented, resulting in a more poli
 2. **Improved workflow**: Prevent accidental duplicate draws
 3. **Cleaner layout**: Consistent button sizing and positioning

-The Daily Journal Prompt Generator web application is now feature-complete with all requested UI improvements implemented.
+## Feedback Mechanism Implementation Plan
+
+### Overview
+Implement a feedback mechanism similar to the old CLI program with updated data structures and workflow. The system will use a single `feedback_historic.json` file with a cyclic buffer structure, replacing the separate `feedback_words.json` and `feedback_historic.json` files.
+
+### Current State Analysis
+**Existing Files:**
+- `feedback_historic.json`: 30 items with `feedback00`-`feedback29` keys, all with `weight: 3`
+- `feedback_words.json`: 6 items with `feedback00`-`feedback05` keys, all with `weight: 3`
+- `ds_feedback.txt`: Template for generating new feedback words
+- Existing API endpoints: `/api/v1/feedback/generate`, `/api/v1/feedback/rate`, `/api/v1/feedback/current`, `/api/v1/feedback/history`
+
+**Current Flow (to be modified):**
+1. Separate current feedback words and historic feedback words
+2. Generate new feedback words via AI
+3. Rate feedback words via API
+
+### New Data Structure
+**Single `feedback_historic.json` cyclic buffer:**
+- **Positions 0-5**: "Queued" words - presented to user for weighting (most recent 6)
+- **Positions 6-11**: "Active" words - used for prompt generation (next 6)
+- **Positions 12-29**: Historic words - older feedback words
+- **All items**: Have `weight` field (default: 3, user-adjusted: 0-6)
+
+**Example structure:**
+```json
+[
+  {"feedback00": "word1", "weight": 3},
+  {"feedback01": "word2", "weight": 3},
+  {"feedback02": "word3", "weight": 3},
+  {"feedback03": "word4", "weight": 3},
+  {"feedback04": "word5", "weight": 3},
+  {"feedback05": "word6", "weight": 3},
+  {"feedback06": "word7", "weight": 3},
+  {"feedback07": "word8", "weight": 3},
+  {"feedback08": "word9", "weight": 3},
+  {"feedback09": "word10", "weight": 3},
+  {"feedback10": "word11", "weight": 3},
+  {"feedback11": "word12", "weight": 3},
+  ... // up to feedback29
+]
+```
+
+### New Workflow
+1. **Prompt Pool Generation** (`/api/v1/prompts/fill-pool`):
+   - Use "active" words (positions 6-11) from `feedback_historic.json`
+   - Send to AI with prompt history for generating new prompts
+   - Start async AI request
+
+2. **User Weighting Interface** (concurrent with AI request):
+   - Show "queued" words (positions 0-5) to user
+   - User adjusts weights (0-6) via UI sliders/buttons
+   - Send updated weights to backend
+
+3. **Feedback Word Generation** (after user weighting):
+   - Use `ds_feedback.txt` template
+   - Send prompt history + weighted "queued" words to AI
+   - Generate 6 new feedback words
+   - Insert new words at position 0 (shifting existing words down)
+   - Add default `weight: 3` to new words
+
+4. **Completion**:
+   - Only after feedback weighting UI process completes
+   - Show success/failure of prompt pool generation
+
+### Implementation Phases
+
+#### Phase 1: Backend Modifications
+1. **Update DataService**:
+   - Remove `load_feedback_words()` and `save_feedback_words()`
+   - Update `load_feedback_historic()` to handle new structure
+   - Add methods to get "queued" (0-5) and "active" (6-11) words
+
+2. **Update PromptService**:
+   - Modify `generate_theme_feedback_words()` to use new structure
+   - Update `update_feedback_words()` to work with queued words
+   - Add method to get active words for prompt generation
+   - Modify `_add_feedback_words_to_history()` to insert at position 0
+
+3. **Update AI Service**:
+   - Ensure `generate_theme_feedback_words()` uses correct data
+   - Add weight field to generated words
+
+4. **Update API Endpoints**:
+   - `/api/v1/feedback/current`: Return queued words (0-5)
+   - `/api/v1/feedback/active`: New endpoint for active words (6-11)
+   - `/api/v1/feedback/history`: Return full feedback_historic
+   - `/api/v1/feedback/rate`: Update weights for queued words
+   - `/api/v1/prompts/fill-pool`: Use active words from feedback
+
+#### Phase 2: Frontend Implementation
+1. **Feedback UI Component**:
+   - Create `FeedbackWeighting.jsx` React component
+   - Display 6 "queued" words with weight sliders (0-6)
+   - Show current weight values
+   - Submit button to send weights to backend
+
+2. **Integration with Prompt Display**:
+   - Modify `PromptDisplay.jsx` to show feedback UI during pool fill
+   - Disable other actions during feedback weighting
+   - Show loading states for both AI requests
+
+3. **State Management**:
+   - Track feedback weighting state
+   - Handle concurrent AI requests
+   - Update UI based on completion status
+
+#### Phase 3: Data Migration
+1. **Migration Script**:
+   - Merge `feedback_words.json` into `feedback_historic.json`
+   - Ensure all items have `weight: 3` field
+   - Maintain cyclic buffer structure (30 items)
+
+2. **Backward Compatibility**:
+   - Update existing code to use new structure
+   - Remove references to old `feedback_words.json`
+
+### Technical Considerations
+
+#### API Design
+```python
+# New/Modified endpoints
+GET /api/v1/feedback/queued          # Get words for weighting (0-5)
+GET /api/v1/feedback/active          # Get words for prompt generation (6-11)
+POST /api/v1/feedback/rate           # Update weights for queued words
+POST /api/v1/feedback/generate       # Generate new feedback words
+GET /api/v1/feedback/history         # Get full feedback history
+```
+
+#### Frontend Component Structure
+```jsx
+// FeedbackWeighting.jsx
+const FeedbackWeighting = () => {
+  const [words, setWords] = useState([]); // {word: string, weight: number}[]
+  const [loading, setLoading] = useState(false);
+
+  // Fetch queued words on mount
+  // Render 6 words with weight sliders
+  // Submit weights to backend
+  // Trigger new feedback word generation
+};
+```
+
+#### State Flow
+1. User clicks "Fill Prompt Pool"
+2. Backend starts AI request with active words (6-11)
+3. Frontend shows feedback weighting UI with queued words (0-5)
+4. User adjusts weights and submits
+5. Backend generates new feedback words, inserts at position 0
+6. Frontend shows completion status of prompt pool generation
+
+### Success Criteria
+1. ✅ Single `feedback_historic.json` file with cyclic buffer
+2. ✅ "Queued" words (0-5) for user weighting
+3. ✅ "Active" words (6-11) for prompt generation
+4. ✅ Concurrent AI requests (prompt generation + feedback generation)
+5. ✅ User-friendly weighting interface
+6. ✅ Proper data migration from old structure
+7. ✅ All existing functionality preserved
+
+### Risks and Mitigations
+1. **Data loss during migration**: Backup existing files, test migration script
+2. **Complex concurrent operations**: Clear loading states, error handling
+3. **UI complexity**: Simple, intuitive weighting interface
+4. **API compatibility**: Version endpoints, gradual rollout
+
+### Next Steps
+1. **Phase 1 Implementation**: Backend modifications
+2. **Phase 2 Implementation**: Frontend UI
+3. **Phase 3 Implementation**: Data migration and testing
+4. **Integration Testing**: End-to-end workflow verification
+
+This plan provides a comprehensive roadmap for implementing the feedback mechanism while maintaining backward compatibility and providing a smooth user experience.
+