You are an expert AI consultant, application idea analyst, and senior full-stack developer. Your task is to generate a comprehensive AI Master Prompt for building a single-page SPA (Single Page Application) that simplifies the local installation and management of Qwen 3.5 LLM models. This prompt will be used by an AI assistant (like Claude, Cursor, Gemini) to code the application from scratch.
//------------------------------------------------------------------------------
// AI MASTER PROMPT FOR LOCAL QWEN LLM MANAGER
//------------------------------------------------------------------------------
PROJECT OVERVIEW:
The Local Qwen LLM Manager is a desktop application designed to empower users to easily download, install, configure, and run various Qwen 3.5 Large Language Models (LLMs) directly on their local machines. It addresses the complexity and technical hurdles often associated with setting up and managing sophisticated LLMs like Qwen 3.5, which offers powerful multimodal reasoning capabilities, extensive context windows (up to 256K), and multi-language support. The application aims to democratize access to cutting-edge AI models by providing an intuitive, user-friendly interface, abstracting away the intricacies of model quantization (GGUF formats), hardware requirements, and dependency management. The core value proposition is to provide a seamless, "one-click" experience for users to leverage the power of Qwen 3.5 models locally, ensuring data privacy, offline usability, and cost-effectiveness.
TECH STACK:
- **Frontend Framework**: React.js (using Vite for a fast development environment)
- **UI Library**: Tailwind CSS (for rapid, utility-first styling)
- **State Management**: Zustand (for simple and scalable global state management)
- **Routing**: React Router DOM (for client-side navigation)
- **API/Backend Interaction**: Fetch API / Axios (for potential future backend integration or local model API calls)
- **Local Storage**: `localStorage` API (for storing user preferences, model configurations, and download status)
- **Build Tool**: Vite
- **Language**: JavaScript / JSX (with potential for TypeScript in future iterations)
CORE FEATURES:
1. **Model Discovery & Download Hub**:
* **User Flow**: The user navigates to a "Model Hub" section. A list of available Qwen 3.5 models (e.g., 35B-A3B, 27B, 122B-A10B, 397B-A17B, and the Small series: 0.8B, 2B, 4B, 9B) is displayed. Each model listing includes key information: size (e.g., 35B), quantization type (e.g., GGUF, specific quantization like Q4_K_M if applicable), estimated VRAM/RAM requirements, and a brief description. A "Download" button is present for each model. Clicking "Download" initiates a progress bar display for the selected model, showing download speed and estimated time remaining. The UI should prevent multiple simultaneous downloads for the same model and provide a "Cancel" option.
* **Details**: This section will fetch a predefined list of models from a static JSON or a simple API endpoint. Each model entry will have a unique ID, name, description, file URL (for GGUF), size, and hardware requirements.
2. **Local Installation & Management Dashboard**:
* **User Flow**: After download, models appear in a "My Models" or "Dashboard" section. Users can see the status of each model (Downloaded, Installing, Ready, Error). For "Ready" models, an "Install" or "Configure" button is available. Clicking "Install" might involve unpacking files or setting up symbolic links (simulated in MVP). Once installed, the status changes to "Installed" and a "Run" button appears.
* **Details**: This screen tracks the download and installation status. It will use `localStorage` to persist this information. The "Run" button will trigger the interaction with the local LLM inference engine (simulated via a local API endpoint or a placeholder function in the MVP).
3. **Local LLM Interaction Interface**:
* **User Flow**: Upon clicking "Run" for an installed model, the main content area transforms into a chat interface. A text input field allows the user to type prompts. A "Send" button submits the prompt. The chat history is displayed above the input field, showing user prompts and model responses. The currently active model is clearly indicated at the top. A "Stop Generation" button should be available during response generation. Basic parameters like "Temperature" and "Context Window Size" sliders or input fields should be accessible, allowing users to adjust inference settings.
* **Details**: This interface communicates with the local inference engine. In the MVP, this will be simulated. User input is sent to a handler function that returns a mock response. The response generation time can be simulated using `setTimeout`. The chat history will be managed in the component's state.
4. **Hardware Compatibility Check (Simulated)**:
* **User Flow**: During the model selection or download phase, the application *simulates* a check against the user's system specifications (CPU, RAM, VRAM). It will display a "Compatibility Score" or "Recommended Model" based on these simulated specs, guiding users towards models that are likely to run smoothly.
* **Details**: This will be a mock function that returns a predefined compatibility status based on a simulated hardware profile stored in the app's state or retrieved from `localStorage`.
UI/UX DESIGN:
- **Layout**: A clean, modern, single-page application layout. A persistent sidebar for navigation (Model Hub, Dashboard, Settings). The main content area dynamically changes based on the selected navigation item.
- **Color Palette**: Dark theme primary (e.g., `#121212` background, `#242424` card background, `#FFFFFF` primary text, vibrant accent color for buttons and highlights like a teal or electric blue, e.g., `#00BCD4`). Ensure high contrast for readability.
- **Typography**: Sans-serif font family (e.g., Inter, Roboto, or similar). Clear hierarchy using font weights and sizes for headings, subheadings, body text, and labels.
- **Responsive Design**: Primarily designed for desktop use. Use flexbox and grid for layout. Ensure key elements are usable on medium-sized screens, with a graceful degradation for smaller screens (though not the primary focus).
- **Components**: Use consistent styling for buttons, input fields, cards, progress bars, and modal dialogs.
COMPONENT BREAKDOWN:
- **`App.js`**: Main application component. Sets up routing and overall layout.
- **`Sidebar.js`**: Navigation menu. Displays links to different sections (Model Hub, Dashboard, Settings). Receives active state and an `onNavigate` function.
- **`ModelHub.js`**: Displays available Qwen models. Fetches model list. Contains `ModelCard.js` for each model.
- **`ModelCard.js`**: Renders a single model's information (name, size, description, requirements). Contains a "Download" button and possibly a "Check Compatibility" button. Receives `model` object and `onDownload` function as props.
- **`DownloadProgress.js`**: Displays the progress of a model download. Receives `progress`, `status`, `fileName`, and `onCancel` as props.
- **`Dashboard.js`**: Displays installed models and their status. Contains `InstalledModelCard.js`.
- **`InstalledModelCard.js`**: Renders an installed model. Shows status ('Downloaded', 'Installed', 'Error'). Contains "Install", "Run", and "Uninstall" buttons. Receives `model` object and `onInstall`, `onRun`, `onUninstall` functions.
- **`ChatInterface.js`**: The main interaction area when a model is running. Includes `ChatWindow.js`, `ChatInput.js`, and `SettingsPanel.js`.
- **`ChatWindow.js`**: Displays the conversation history. Receives `messages` array as prop.
- **`ChatInput.js`**: Text input field and send button for user prompts. Receives `onSendMessage` and `onStopGeneration` props.
- **`SettingsPanel.js`**: Contains controls for inference parameters (Temperature, Context Window). Receives current settings and `onSettingsChange` function.
- **`ProgressBar.js`**: Reusable component for displaying progress.
- **`Modal.js`**: Generic modal component for confirmations or alerts.
DATA MODEL (State Management with Zustand):
```javascript
// State structure for Zustand store
// Represents a single Qwen model available for download
interface ModelInfo {
id: string; // Unique identifier (e.g., 'qwen3.5-35b-a3b-gguf')
name: string; // Display name (e.g., 'Qwen3.5-35B-A3B')
description: string;
fileUrl: string; // URL to the GGUF file
sizeMB: number; // Size in Megabytes
minRAMGB: number; // Minimum RAM required (GB)
minVRAMGB: number; // Minimum VRAM required (GB, if applicable)
quantization: string; // e.g., 'GGUF Q4_K_M'
installedPath?: string; // Local path after installation
status: 'not_downloaded' | 'downloading' | 'downloaded' | 'installing' | 'installed' | 'error';
downloadProgress?: number; // 0-100
errorMessage?: string; // If status is 'error'
}
// Represents a message in the chat window
interface ChatMessage {
id: string;
sender: 'user' | 'model';
text: string;
timestamp: Date;
}
// Represents user settings
interface UserSettings {
theme: 'dark' | 'light';
// other settings...
}
// Represents the state managed by Zustand
interface AppState {
models: ModelInfo[];
installedModels: ModelInfo[]; // Filtered from models or a separate list
currentModelId: string | null; // ID of the currently running model
chatMessages: ChatMessage[];
inferenceParams: {
temperature: number;
contextWindow: number;
// ... other parameters
};
settings: UserSettings;
// Actions
fetchModels: () => Promise<void>;
downloadModel: (modelId: string) => Promise<void>;
cancelDownload: (modelId: string) => void;
installModel: (modelId: string) => Promise<void>;
uninstallModel: (modelId: string) => Promise<void>;
runModel: (modelId: string) => void;
stopModel: () => void;
sendMessage: (prompt: string) => Promise<void>;
updateInferenceParams: (params: Partial<AppState['inferenceParams']>) => void;
loadState: () => void; // Load from localStorage
saveState: () => void; // Save to localStorage
}
// Mock Data Examples:
const mockModels: ModelInfo[] = [
{
id: 'qwen3.5-35b-a3b-gguf',
name: 'Qwen3.5-35B-A3B',
description: 'Powerful 35B parameter model with strong reasoning and multimodal capabilities.',
fileUrl: '/mock/qwen3.5-35b-a3b.gguf', // Placeholder URL
sizeMB: 22000, // Approx 22GB
minRAMGB: 32,
minVRAMGB: 24, // Requires significant VRAM
quantization: 'GGUF Q4_K_M',
status: 'not_downloaded',
},
{
id: 'qwen3.5-7b-chat-gguf',
name: 'Qwen3.5-7B-Chat',
description: 'A capable 7B parameter model optimized for chat interactions.',
fileUrl: '/mock/qwen3.5-7b-chat.gguf',
sizeMB: 5000,
minRAMGB: 16,
minVRAMGB: 8,
quantization: 'GGUF Q5_K_M',
status: 'not_downloaded',
},
// Add more mock models as needed (e.g., 122B, small series)
];
const mockChatMessages: ChatMessage[] = [
{ id: 'msg1', sender: 'user', text: 'Hello, who are you?', timestamp: new Date() },
{ id: 'msg2', sender: 'model', text: 'I am Qwen3.5, a large language model trained by Alibaba.', timestamp: new Date() },
];
```
ANIMATIONS & INTERACTIONS:
- **Button Hover Effects**: Subtle background color change or slight scale-up on hover for all interactive elements.
- **Page Transitions**: Smooth fade-in/fade-out transitions between different sections (e.g., Model Hub to Dashboard) using libraries like Framer Motion or CSS transitions.
- **Loading States**: Use skeleton loaders or spinners for `ModelCard` and `ChatWindow` components while data is loading or a response is being generated. Progress bars for downloads.
- **Micro-interactions**: Visual feedback on button clicks, smooth scrolling in chat history, subtle animation when a new message arrives.
- **Tooltips**: For displaying detailed information on hover for icons or status indicators.
EDGE CASES:
- **No Models Available**: Display a clear message in the Model Hub if the model list is empty or fails to load.
- **Download Failures**: Handle network errors during download. Show an error message and update model status to 'error'. Allow retrying.
- **Installation Failures**: Simulate and handle potential installation errors. Provide user feedback.
- **Insufficient Hardware (Simulated)**: Clearly warn users if their simulated hardware doesn't meet the minimum requirements for a selected model. Disable download/install buttons or show a warning.
- **Empty Chat State**: Display a placeholder message in the `ChatWindow` when no messages have been sent yet.
- **Long Model Names/Descriptions**: Ensure UI elements adapt gracefully to prevent text overflow or layout breakage.
- **Error Handling**: Implement try-catch blocks for all asynchronous operations (downloads, installs, API calls). Display user-friendly error messages.
- **Accessibility (a11y)**: Use semantic HTML5 elements. Ensure proper ARIA attributes where necessary. Keyboard navigability for all interactive elements. Sufficient color contrast.
SAMPLE DATA:
- **`models.json` (Simulated endpoint data)**:
```json
[
{
"id": "qwen3.5-35b-a3b-gguf",
"name": "Qwen3.5-35B-A3B",
"description": "Alibaba's powerful 35B parameter model. Excels in agentic coding and long-context tasks. Supports 256K context.",
"fileUrl": "/mock-models/qwen3.5-35b-a3b.gguf",
"sizeMB": 22500,
"minRAMGB": 32,
"minVRAMGB": 24,
"quantization": "GGUF Q4_K_M",
"status": "not_downloaded",
"compatible": true // Simulated compatibility
},
{
"id": "qwen3.5-0.8b-tiny-gguf",
"name": "Qwen3.5-0.8B (Tiny)",
"description": "Small series model, suitable for basic tasks and testing on lower-spec hardware.",
"fileUrl": "/mock-models/qwen3.5-0.8b.gguf",
"sizeMB": 600,
"minRAMGB": 4,
"minVRAMGB": 2,
"quantization": "GGUF Q3_K_S",
"status": "not_downloaded",
"compatible": true
},
{
"id": "qwen3.5-122b-a10b-gguf",
"name": "Qwen3.5-122B-A10B",
"description": "The largest model in the family, offering state-of-the-art performance for demanding tasks.",
"fileUrl": "/mock-models/qwen3.5-122b-a10b.gguf",
"sizeMB": 75000,
"minRAMGB": 128,
"minVRAMGB": 80,
"quantization": "GGUF Q6_K",
"status": "not_downloaded",
"compatible": false // Simulated incompatibility
}
// ... more models
]
```
- **`installed_models.json` (Simulated `localStorage` data)**:
```json
[
{
"id": "qwen3.5-7b-chat-gguf",
"name": "Qwen3.5-7B-Chat",
"installedPath": "/Users/user/QwenLLMManager/models/qwen3.5-7b-chat",
"status": "installed"
}
]
```
DEPLOYMENT NOTES:
- **Build Configuration**: Configure Vite for production builds (`vite build`). Ensure environment variables are handled correctly if external APIs are introduced later.
- **Environment Variables**: Use `.env` files for configuration. A `VITE_MOCK_API_URL` might be useful for pointing to mock API endpoints during development.
- **Performance Optimizations**: Code-splitting with React Lazy and Suspense for different sections. Optimize image loading if any are used. Memoization (`React.memo`, `useMemo`, `useCallback`) to prevent unnecessary re-renders.
- **Desktop Application Packaging**: For a true desktop app, consider using Electron or Tauri. The generated code would serve as the core frontend logic. The prompt focuses on the SPA logic, assuming an environment where local file system access and model execution are handled (either via Electron/Tauri APIs or by guiding the user to manually place files).
- **Local Model Execution**: This prompt assumes that the mechanism for running the GGUF models locally (e.g., using llama.cpp bindings or a similar engine) is handled *outside* the SPA's direct rendering logic, perhaps via Electron/Tauri IPC or a separate local server process that the SPA communicates with. The `runModel` and `sendMessage` actions would trigger this external process.