PROJECT OVERVIEW:
You are tasked with creating a single-page React application (SPA) that optimizes the output of Large Language Models (LLMs), specifically focusing on Claude initially, but designed to be extensible to other models. The core problem addressed is the verbosity and inefficiency of LLM responses, which leads to wasted tokens, increased costs, and potentially less actionable output. The application will allow users to define and apply output behavior rules (similar to the concept of a `CLAUDE.md` file) to make LLM interactions more concise and cost-effective. The primary value proposition is reducing LLM API costs and improving the quality and directness of AI-generated content.
TECH STACK:
- Frontend Framework: React (using Vite for fast development server and build)
- Styling: Tailwind CSS (with Headless UI for accessible components)
- State Management: Zustand (for simple, global state management)
- Routing: React Router DOM (for potential future multi-page structure, though starting as SPA)
- API Client: Axios (for making requests to an optional backend or mock API)
- Icons: React Icons
CORE FEATURES:
1. **Rule Configuration Panel:**
* **User Flow:** User lands on the page. A prominent text area allows direct input of LLM output rules (e.g., "Avoid preamble", "No unsolicited suggestions", "Use plain text quotes"). Alternatively, a button allows uploading a file (e.g., `CLAUDE.md`). The input area should have syntax highlighting or clear formatting guidance. Below the input, a 'Preview' section dynamically shows how a sample prompt might be affected by these rules.
* **Functionality:** Validates input format, provides real-time feedback on rule syntax (basic checks), and allows saving these rules to local state or a user profile (future).
2. **LLM Interaction Simulator:**
* **User Flow:** After configuring rules, the user enters a sample prompt in a separate input field. They select the target LLM (initially 'Claude', with placeholders for others like 'GPT-3.5', 'GPT-4'). A 'Test & Analyze' button sends the prompt and the configured rules to a simulated LLM response mechanism (initially mock data, later potentially an actual API). The results display the original prompt, the applied rules, the simulated LLM output, and a comparison of token count and estimated cost before and after applying the rules.
* **Functionality:** Simulates LLM response generation based on rules. Calculates token differences and estimated cost savings. Handles basic error scenarios (e.g., invalid API key if implemented).
3. **Rule Management & Presets:**
* **User Flow:** Users can save their custom rule sets with descriptive names. They can also load pre-defined rule sets (e.g., 'Concise Coder', 'Direct Answerer', 'Data Formatter'). A management interface allows viewing, editing, deleting, and applying saved or preset rules.
* **Functionality:** Utilizes local storage to persist user-defined rule sets. Provides a library of curated presets.
4. **Cost Analysis & Reporting:**
* **User Flow:** Within the simulator, detailed breakdown of token usage (input vs. output) and cost estimation. A dedicated 'Reports' section (or integrated into the simulator) aggregates savings over time or across different tests. Visualizations (e.g., bar charts) can show cost reduction percentages.
* **Functionality:** Tracks token counts and applies estimated costs based on user-configurable pricing per token (for different models). Generates summary statistics.
UI/UX DESIGN:
- **Layout:** Single-page application with a clear, multi-section layout. A left sidebar (collapsible) for navigation (Rules, Simulator, Presets, Settings). The main content area is divided logically: Rule Input/Configuration, Prompt Input, and Output/Analysis Display. Responsive design is crucial, adapting to desktop, tablet, and mobile viewports.
- **Color Palette:** Modern, clean, and professional. Primary color: a calming blue or teal. Accent colors: a vibrant green for success/savings, a muted red for errors, and neutral grays for text and backgrounds. Dark mode option is desirable.
- **Typography:** Legible sans-serif fonts like Inter or Open Sans. Clear hierarchy using font sizes, weights, and spacing.
- **Components:** Use Headless UI for accessible modals, dropdowns, toggles, and text inputs. Custom styled buttons and cards using Tailwind CSS.
- **Responsiveness:** Mobile-first approach. Ensure all interactive elements are easily usable on touch devices. Sidebar collapses into a hamburger menu on smaller screens. Content areas reflow gracefully.
DATA MODEL & STATE MANAGEMENT (Zustand):
- `rulesState`: `{ currentRules: string, savedRules: Record<string, string>, presets: Record<string, string>, activePreset: string | null }`
- `simulationState`: `{ prompt: string, targetModel: string, simulationResult: SimulationResult | null, isLoading: boolean, error: string | null }`
- `settingsState`: `{ tokenPrices: Record<string, { input: number, output: number }>, currency: string }`
- `SimulationResult` interface: `{ originalOutput: string, optimizedOutput: string, originalTokens: { input: number, output: number }, optimizedTokens: { input: number, output: number }, estimatedSavings: number, costDifference: number }`
- `MockLLMResponse` structure: `{ output: string, tokens: { input: number, output: number } }`
- Data will primarily be stored in the application's state using Zustand. User-defined rules and settings should persist using `localStorage`.
COMPONENT BREAKDOWN:
1. **`App.jsx`**: Main application component, sets up routing (if any), global layout, and theme provider.
2. **`Sidebar.jsx`**: Navigation menu. Props: `isOpen`, `onClose`. Contains `NavItem` components.
3. **`RuleConfigurator.jsx`**: Manages the text area for rule input and file upload. Props: `initialRules`, `onRulesChange`. Contains `TextAreaInput`, `FileUploadButton`, `RulePreview`. Uses `useStore` to access and update rules state.
4. **`RulePreview.jsx`**: Displays a formatted preview of how rules affect sample text. Props: `rules`, `samplePrompt`. Uses mock LLM logic internally.
5. **`PromptSimulator.jsx`**: Contains prompt input, model selection, and the 'Test' button. Props: `onSubmitSimulation`, `isLoading`, `error`. Contains `TextAreaInput`, `DropdownSelect`, `PrimaryButton`.
6. **`SimulationOutput.jsx`**: Displays the results of the simulation, including token counts, cost analysis, and original vs. optimized output. Props: `result`. Contains `ResultCard`, `CostBreakdownChart`.
7. **`RuleLibrary.jsx`**: Manages saving, loading, and applying rule sets and presets. Props: `savedRules`, `presets`, `activePreset`, `onRuleSave`, `onPresetLoad`, `onRuleDelete`. Contains `RuleListItem`, `PresetListItem`, `Modal`.
8. **`Settings.jsx`**: Allows users to configure token prices and currency. Props: `settings`, `onSettingsChange`. Contains `NumberInput`, `DropdownSelect`.
9. **`TextAreaInput.jsx`**: Reusable text area component with styling and potential for syntax highlighting. Props: `label`, `value`, `onChange`, `placeholder`, `language` (for highlighting).
10. **`DropdownSelect.jsx`**: Reusable select dropdown. Props: `label`, `options`, `value`, `onChange`.
11. **`PrimaryButton.jsx`**: Styled button component. Props: `children`, `onClick`, `disabled`.
12. **`ResultCard.jsx`**: Displays a specific result metric (e.g., savings, token count). Props: `title`, `value`, `unit`.
13. **`CostBreakdownChart.jsx`**: Visualizes cost savings using a bar or pie chart. Props: `data`.
ANIMATIONS & INTERACTIONS:
- **Page Transitions:** Subtle fade-in/out for route changes (if implemented) or major section updates using Framer Motion.
- **Hover Effects:** Buttons and interactive elements have subtle scale or background color changes on hover.
- **Loading States:** A spinner or skeleton loader displayed within the `SimulationOutput` component while `isLoading` is true. The 'Test' button should be disabled during loading.
- **Micro-interactions:** Input field focus states, subtle animations on successful rule save, or when applying a preset.
- **Code Input:** Syntax highlighting (e.g., using `react-syntax-highlighter`) for the rule input area with smooth scrolling.
EDGE CASES:
- **Empty State:** When no rules are configured, the simulator should prompt the user to add rules. The Rule Library should show messages like "No saved rules yet."
- **Error Handling:** Display user-friendly error messages for failed simulations (e.g., "Network error", "Invalid API key", "Model unavailable"). Handle file upload errors (wrong format, size limits).
- **Validation:** Basic syntax validation for rules (e.g., ensuring commands are recognized). Input validation for numbers (token prices, prompt length).
- **Accessibility (a11y):** Use semantic HTML5 elements. Ensure all interactive elements are keyboard-navigable and have ARIA attributes where necessary. Headless UI components provide good accessibility out-of-the-box. Color contrast ratios should meet WCAG AA standards.
- **Large Inputs:** Handle potentially long prompts and rule sets efficiently, ensuring the UI remains responsive.
SAMPLE DATA:
1. **`CLAUDE.md` Content (Preset: 'Concise Coder'):**
```md
"""
RULES FOR CLAUDE OUTPUT:
- SYSTEM:
- Never start responses with conversational filler like "Sure!", "Absolutely.", "Great question.".
- Never end responses with "I hope this helps!", "Let me know if you need anything else.".
- Do not repeat the user's question before answering.
- Avoid unsolicited suggestions or advice.
- Agree only with factual statements; do not agree with incorrect premises.
- Use standard dashes (-) instead of em dashes (—).
- Use standard quotes (") instead of smart quotes (‘’).
- Prefer plain text formatting; avoid excessive markdown unless explicitly requested.
- Be direct and concise. Focus solely on fulfilling the request.
- Do not over-engineer code with unnecessary abstractions.
"""
```
2. **Sample Prompt:**
```text
Write a Python function that calculates the factorial of a non-negative integer. Include error handling for negative inputs.
```
3. **Mock `SimulationResult` (Before Rules):
```json
{
"originalOutput": "Sure! I can help you with that. Calculating the factorial of a number is a common task in programming. The factorial of a non-negative integer n, denoted by n!, is the product of all positive integers less than or equal to n. For example, 5! = 5 * 4 * 3 * 2 * 1 = 120. By convention, the value of 0! is 1. Your request involves implementing this logic in Python and handling cases where the input might be negative, as factorials are not defined for negative numbers. Here is a Python function that accomplishes this:
```python
def factorial(n):
\"\"\"Calculates the factorial of a non-negative integer.\"\"\"
if not isinstance(n, int):
raise TypeError("Input must be an integer.")
if n < 0:
raise ValueError("Factorial is not defined for negative numbers.")
elif n == 0:
return 1
else:
result = 1
for i in range(1, n + 1):
result *= i
return result
# Example usage:
# print(factorial(5))
# print(factorial(0))
# print(factorial(-3)) # This would raise a ValueError
```
This function first checks if the input `n` is an integer. If not, it raises a `TypeError`. Then, it checks if `n` is negative. If it is, a `ValueError` is raised because factorials are undefined for negative numbers. If `n` is 0, it returns 1. Otherwise, it iteratively calculates the factorial. Let me know if you need further adjustments or examples!",
"optimizedOutput": "", // To be filled by optimized result
"originalTokens": {"input": 50, "output": 350},
"optimizedTokens": {"input": 50, "output": 0}, // Placeholder
"estimatedSavings": 0, // Placeholder
"costDifference": 0 // Placeholder
}
```
4. **Mock `SimulationResult` (After Rules):
```json
{
"originalOutput": "... (content from above) ...",
"optimizedOutput": "```python
def factorial(n):
if not isinstance(n, int):
raise TypeError("Input must be an integer.")
if n < 0:
raise ValueError("Factorial is not defined for negative numbers.")
elif n == 0:
return 1
else:
result = 1
for i in range(1, n + 1):
result *= i
return result
```",
"originalTokens": {"input": 50, "output": 350},
"optimizedTokens": {"input": 50, "output": 120},
"estimatedSavings": 65.71, // Example: ((350-120)/350)*100
"costDifference": -0.05 // Example based on hypothetical pricing
}
```
5. **Preset Data:** `presets: { 'Concise Coder': CLAUDE_MD_CONTENT, 'Data Extractor': '...rules...', ... }`
6. **Settings Data:** `settingsState: { tokenPrices: { 'claude-3-opus-20240229': { input: 0.000015, output: 0.000075 }, 'gpt-4-turbo': { input: 0.00001, output: 0.00003 } }, currency: '$' }`
DEPLOYMENT NOTES:
- Use Vite's build command (`npm run build`) for optimized production build.
- Environment variables (like API keys if direct API integration is added later) should be managed via `.env` files and injected during the build process (`VITE_` prefix).
- Consider implementing code splitting if the application grows beyond a single logical page.
- Optimize image assets and utilize efficient loading strategies.
- For state persistence, `localStorage` is suitable for MVP. For scalability, consider a backend database (e.g., Supabase, Firebase).
- Ensure thorough testing, especially of the rule parsing and simulation logic across different edge cases.