```markdown
# AI Master Prompt: Local AI Setup Assistant for macOS
## 1. PROJECT OVERVIEW
The **Local AI Setup Assistant** is a macOS desktop application designed to simplify the process of installing, configuring, and managing large language models (LLMs) like Google's Gemma on Apple Silicon Macs. It addresses the technical complexity and time investment required by users to set up tools like Ollama and download large model files via the command line. The application aims to provide a seamless, graphical user interface (GUI) experience, enabling users to run powerful AI models locally with minimal effort, optimizing resource usage and ensuring smooth operation. The core value proposition is democratizing access to local AI, making it as easy as installing any other macOS application.
## 2. TECH STACK
* **Frontend Framework:** React (using Vite for a fast development experience)
* **UI Library/Framework:** Tailwind CSS (for utility-first styling)
* **State Management:** Zustand (for simple, scalable global state management)
* **Cross-Platform Desktop App Framework:** Electron.js (to package the React app as a native macOS application)
* **Shell Command Execution:** `child_process` module (Node.js API within Electron) for running shell commands like `brew`, `ollama`.
* **Progress Indicators:** Libraries like `react-spinners` or custom SVG animations.
* **Notifications:** Electron's `Notification` API or a library like `react-toastify`.
* **Iconography:** `react-icons` or custom SVG icons.
## 3. CORE FEATURES & USER FLOWS
### 3.1. Ollama Installation & Management
* **User Flow:**
1. User clicks 'Install Ollama' button.
2. App checks if Homebrew is installed. If not, prompts user to install it or provides a link.
3. App executes `brew install --cask ollama-app` command using `child_process`.
4. A progress indicator shows the installation status (fetching, installing).
5. Upon successful installation, the button changes to 'Ollama Installed' or 'Launch Ollama'.
6. User can click 'Launch Ollama' to open the Ollama application (`open -a Ollama`).
7. An option to 'Enable Auto-Start on Login' will be presented, which configures the Ollama app to launch automatically when the user logs in.
8. 'Check Ollama Status' button will execute `ollama list` and display the output.
* **Details:** Handles potential errors during brew installation, provides clear feedback.
### 3.2. LLM Model Download & Management
* **User Flow:**
1. User navigates to the 'Models' tab.
2. A list of compatible, popular models (e.g., Gemma 4 8B, Gemma 4 26B, Llama 3 8B, Mistral 7B) is displayed with their approximate sizes and resource requirements (RAM estimate).
3. User clicks the 'Download' button next to a desired model.
4. The app executes `ollama pull <model_name>:<tag>`.
5. A detailed progress bar shows the download percentage and speed.
6. Once downloaded, the model appears in the 'My Models' list.
7. Users can select a model from 'My Models' to 'Run' or 'Delete'.
8. Clicking 'Run' will execute `ollama run <model_name>` and open a chat interface within the app.
* **Details:** Clear warnings about large download sizes and disk space. Ability to cancel downloads. Distinction between model sizes and their impact on performance (e.g., 8B vs 26B on 16GB RAM). Option to specify quantization levels (e.g., Q4_K_M) if supported by Ollama CLI.
### 3.3. Local Chat Interface
* **User Flow:**
1. User selects a downloaded model from the 'My Models' list.
2. User clicks the 'Chat' button.
3. A simple chat interface appears within the app.
4. User types a prompt into the input field and presses Enter or clicks 'Send'.
5. The app sends the prompt to the selected local model via `ollama run <model_name>` or an equivalent API call if Ollama runs as a server.
6. The model's response is displayed in the chat window.
7. Display of GPU/CPU utilization during inference (e.g., using `ollama ps` or similar).
* **Details:** Basic chat history. Ability to clear chat. Clear indication of which model is currently active.
### 3.4. Resource Monitoring
* **User Flow:**
1. A dedicated 'System Monitor' section or integrated view shows real-time CPU, RAM, and potentially VRAM usage.
2. This data is gathered by periodically executing system commands or using platform-specific APIs.
3. Visualizations (e.g., graphs or simple percentage displays) show current load.
4. Highlights when resource usage is critical (e.g., >90% RAM usage) and suggests actions (e.g., closing other apps, unloading heavy models).
* **Details:** Focus on Apple Silicon's unified memory architecture. Provides context like 'Total Unified Memory' vs 'Used by Ollama' vs 'Used by System'.
## 4. UI/UX DESIGN
* **Layout:** Single-page application (SPA) structure within Electron. A sidebar navigation for 'Home' (Dashboard), 'Models', 'Chat', 'Settings'. Main content area displays the selected section.
* **Color Palette:**
* Primary: Dark mode dominant. Deep blues (`#1a202c`), grays (`#2d3748`), and blacks (`#000000`).
* Accent: A vibrant tech-blue (`#4299e1`) or electric purple (`#6b46c1`) for buttons, active states, and highlights.
* Secondary: Lighter grays (`#a0aec0`) for text and less important elements.
* Success/Warning: Green (`#48bb78`) and Orange/Red (`#ed8936`/`#f56565`) for status indicators.
* **Typography:** Clean, modern sans-serif font. Use Tailwind's default `font-sans` (Inter, or similar). Clear hierarchy using font sizes and weights (e.g., `text-lg`, `font-semibold` for headings, `text-base` for body).
* **Responsiveness:** While primarily a desktop app, ensure UI elements are well-spaced and readable on various Mac screen sizes. Elements should reflow gracefully, not just scale.
* **Interactions:** Subtle hover effects on buttons and list items. Smooth transitions between sections. Clear loading spinners/skeletons when fetching data or running commands.
## 5. COMPONENT BREAKDOWN
* **`App.jsx`:** Main application component. Sets up Electron main process communication, routing (using React Router or similar), and global layout (Sidebar + Content).
* **`Sidebar.jsx`:** Navigation component. Renders links for different app sections. Active link styling.
* **`Dashboard.jsx`:** Home screen. Shows quick status (Ollama installed?), quick actions (Install/Launch Ollama), maybe a summary of downloaded models.
* **`OllamaManager.jsx`:** Handles Ollama installation and launch logic. Contains buttons for 'Install Ollama', 'Launch Ollama', 'Enable Auto-Start'. Uses `useShellCommand` hook.
* **`ModelList.jsx`:** Displays available models for download. Fetches model data (mock or from a simple config file initially). Each item has a 'Download' button.
* **`ModelItem.jsx`:** Represents a single model in the list. Shows name, size, description, download button. Handles download state (idle, downloading, complete, error).
* **`MyModels.jsx`:** Displays downloaded models. Lists models from state. Each item has 'Chat' and 'Delete' buttons.
* **`ChatInterface.jsx`:** The chat UI. Input field, message display area, send button. Manages chat history state. Uses `useShellCommand` to send prompts.
* **`SystemMonitor.jsx`:** Displays CPU/RAM usage. Uses a hook to periodically fetch system stats.
* **`ProgressBar.jsx`:** Reusable component for download/install progress.
* **`Spinner.jsx`:** Reusable loading indicator.
* **`useShellCommand` Hook:** Custom hook to abstract the `child_process` logic. Takes a command string, executes it, manages stdout/stderr, loading state, and errors. Returns `data`, `isLoading`, `error`.
## 6. DATA MODEL & STATE MANAGEMENT
* **State Management (Zustand):**
* `ollamaStore`: `{ isInstalled: boolean, isRunning: boolean, launchAtLogin: boolean }`
* `modelsStore`: `{ availableModels: ModelInfo[], downloadedModels: DownloadedModelInfo[], downloadProgress: { [modelName: string]: number } }`
* `chatStore`: `{ activeModel: string | null, messages: ChatMessage[], input: string }`
* `systemStore`: `{ cpuUsage: number, ramUsage: number, totalRam: number }`
* **`ModelInfo` Interface:** `{ id: string, name: string, tag: string, description: string, size: string, ramRequired: string, gpuRecommended: boolean }`
* **`DownloadedModelInfo` Interface:** `{ id: string, name: string, tag: string, size: string, downloadDate: string }`
* **`ChatMessage` Interface:** `{ role: 'user' | 'assistant', content: string, timestamp: string }`
* **Mock Data:** Initial `availableModels` can be hardcoded or loaded from a JSON file within the app's `public` directory. `downloadedModels` will be managed in state, potentially persisting to local storage or a file.
## 7. ANIMATIONS & INTERACTIONS
* **Buttons:** Subtle scaling (`scale-95`) and background color change on hover/active states using Tailwind's `hover:` and `active:` variants.
* **Page Transitions:** Fade-in/fade-out effect for content sections when navigating between tabs (using Framer Motion or CSS transitions).
* **Loading States:** Replace content with placeholder `div`s or skeleton loaders while data is being fetched or commands are running. Use `react-spinners` for inline loading indicators.
* **Download Progress:** Animated progress bars that fill smoothly.
* **Model List:** Subtle fade-in for new models as they are added.
* **Chat Bubbles:** Fade-in animation for incoming and outgoing messages.
## 8. EDGE CASES & ERROR HANDLING
* **Ollama Not Installed:** Gracefully handle attempts to use Ollama commands. Provide clear prompts and buttons to install.
* **Homebrew Not Found:** Detect missing Homebrew and guide the user through its installation.
* **Download Failures:** Network errors, insufficient disk space. Show clear error messages, allow retry. Update model status to 'Error'.
* **Model Execution Errors:** Ollama server not running, incompatible model. Display specific error messages from Ollama.
* **Resource Exhaustion:** If RAM/CPU usage critical, display prominent warnings. Potentially disable 'Run Model' button if system is unresponsive. Suggest closing the app or unloading models.
* **Empty States:** When no models are downloaded, the 'My Models' list should show a friendly message and a prompt to download models.
* **Permissions:** Ensure the app has necessary permissions if it needs to interact with system files or launch other applications.
* **Accessibility (a11y):** Use semantic HTML, ensure sufficient color contrast, support keyboard navigation, use ARIA attributes where necessary.
## 9. SAMPLE DATA (Mock Data Formats)
* **`availableModels.json` (or initial state in Zustand):**
```json
[
{
"id": "gemma4-8b",
"name": "Gemma 4 (8B)",
"tag": "latest",
"description": "Google's lightweight, state-of-the-art GGUF model. Optimized for efficiency.",
"size": "~4.7 GB",
"ramRequired": "~8 GB",
"gpuRecommended": true
},
{
"id": "gemma4-26b",
"name": "Gemma 4 (26B)",
"tag": "latest",
"description": "A larger version of Gemma, offering enhanced reasoning capabilities. Requires more resources.",
"size": "~15 GB",
"ramRequired": "~20 GB",
"gpuRecommended": true
},
{
"id": "llama3-8b",
"name": "Llama 3 (8B)",
"tag": "latest",
"description": "Meta's powerful open-source language model.",
"size": "~4.1 GB",
"ramRequired": "~8 GB",
"gpuRecommended": true
}
]
```
* **`downloadedModels` state example:**
```javascript
// In downloadedModels store
[
{
"id": "gemma4-8b",
"name": "Gemma 4 (8B)",
"tag": "latest",
"size": "4.7 GB",
"downloadDate": "2024-05-15T10:30:00Z"
}
]
```
* **`chatMessages` state example:**
```javascript
// In chatStore
[
{
"role": "user",
"content": "Hello, what is your name?",
"timestamp": "2024-05-15T10:35:00Z"
},
{
"role": "assistant",
"content": "I am a large language model, trained by Google.",
"timestamp": "2024-05-15T10:35:05Z"
}
]
```
## 10. DEPLOYMENT NOTES
* **Build Process:** Use Vite's build command (`npm run build`) for the React frontend. Use Electron Builder (`npm run dist`) to package the application for macOS (`.dmg` file).
* **Environment Variables:** Use `.env` files for managing build-time variables (e.g., default API endpoints if any were used, though not expected for this local-first app).
* **`main.js` (Electron Main Process):** Configure window creation, handle IPC communication between renderer (React) and main process, manage shell command execution.
* **`preload.js` (Electron Preload Script):** Securely expose Node.js APIs (like `child_process` via contextBridge) to the renderer process.
* **Performance Optimizations:** Code splitting with Vite. Efficient state management. Minimize re-renders. Optimize shell command execution to avoid blocking the UI thread.
* **Auto-Updates:** Leverage Electron Builder's auto-update capabilities to provide seamless updates to users.
* **Packaging:** Ensure correct signing and notarization for macOS distribution to avoid Gatekeeper warnings.
```