# AI Master Prompt for 'Yerel AI: Modeller Cepte' (Local AI: Models in Your Pocket)
## 1. PROJECT OVERVIEW
**Project Title:** Local AI: Models in Your Pocket
**Value Proposition:** Empower users to effortlessly download, manage, and run powerful open-source AI models directly on their local devices (desktops, laptops, potentially mobile in the future). This application addresses the growing demand for running AI locally, driven by concerns over data privacy, cost, and offline accessibility, while abstracting away the complex setup and configuration typically required.
**Problem Solved:** Users often find it challenging and time-consuming to set up and run large language models (LLMs) and other AI models locally due to complex dependencies, hardware requirements, and varied model formats. This application provides a streamlined, user-friendly interface to discover, download, and interact with these models without requiring deep technical expertise.
**Target Audience:** AI enthusiasts, developers, data scientists, privacy-conscious individuals, and users with limited internet connectivity or budget constraints. It caters to those who want to experiment with cutting-edge AI without relying on cloud services.
**Core Goal:** To be the go-to, single-page application (SPA) for discovering, installing, and running open-source AI models locally, making local AI accessible to a broader audience.
## 2. TECH STACK
* **Frontend Framework:** React (using Vite for fast development server and build process)
* **Styling:** Tailwind CSS (with Headless UI for accessible, unstyled components)
* **State Management:** Zustand (lightweight, performant, and easy to integrate for global state)
* **Routing:** React Router DOM (for potential future multi-page structure, though initially SPA)
* **UI Components:** Headless UI (for accessible and customizable components), potentially Radix UI for advanced primitives.
* **Icons:** Heroicons or similar SVG icon library.
* **API/Data Fetching:** `fetch` API or Axios for potential backend interactions (if any in future), but primarily focusing on local operations and state management for MVP.
* **Local Model Execution:** This is the most crucial and challenging part. For MVP, we will simulate the *download* and *management* aspects. Actual local execution might involve integrating with existing command-line tools (like `ollama` or `llama.cpp` binaries) via Electron or similar desktop app frameworks, or a WebAssembly-based runtime if feasible for specific model types. For this prompt, we'll focus on the frontend application structure assuming an abstraction layer exists or will be built for interacting with local model runners.
* **Desktop Application Packaging:** Electron (for creating cross-platform desktop applications - Windows, macOS, Linux). This allows the app to interact with the local file system and potentially run local binaries.
## 3. CORE FEATURES (MVP)
1. **Model Discovery & Catalog:**
* **User Flow:** User lands on the app. The main view displays a searchable and filterable catalog of available AI models. Each model card shows its name, provider (Meta, Mistral, etc.), size (e.g., 4GB), key features (e.g., 'chat', 'reasoning'), quantization levels (Q4_K_M, Q8_0), and required context length (128K ctx). Filters allow sorting by size, popularity, or category (e.g., Chat, Code, Vision). A search bar enables quick finding.
* **Details:** Clicking a model card opens a detailed view with more information, including download links (or simulated download buttons), compatibility notes, and potentially example prompts.
2. **One-Click Download & Installation:**
* **User Flow:** From the model detail view or catalog, the user clicks a 'Download' button. The application initiates a download process (simulated in frontend, actual via Electron's IPC or file system APIs). A progress indicator is displayed. Once downloaded, the model is 'installed' (i.e., added to a local registry managed by the app).
* **Details:** The app needs to manage downloaded files, store metadata about them, and handle potential download interruptions or errors.
3. **Local Model Management:**
* **User Flow:** A dedicated 'My Models' section lists all downloaded and installed models. Users can view their status (Downloaded, Running, Error), size, and other metadata. Options to 'Run', 'Stop', 'Delete', or 'Update' (if applicable) are available.
* **Details:** This section provides an overview of the user's local AI model library.
4. **Simple Interaction Interface:**
* **User Flow:** After selecting a downloaded model and clicking 'Run', the app launches a simple chat interface. The user can type prompts, send them to the (simulated/abstracted) local model, and receive responses. The interface clearly indicates which model is currently active.
* **Details:** This provides immediate value by allowing users to test the downloaded models. For MVP, this interaction will be a simulation or a direct integration with a lightweight local runner like `ollama` if Electron is used.
5. **Basic Resource Monitoring:**
* **User Flow:** While a model is running, a small, non-intrusive panel displays real-time (simulated) CPU usage, RAM usage, and VRAM usage (if applicable).
* **Details:** Gives users a basic understanding of the computational cost of running models locally.
## 4. UI/UX DESIGN
* **Layout:** Single Page Application (SPA) with a persistent sidebar navigation and a main content area. Sidebar includes links to 'Discover Models', 'My Models', 'Settings'.
* **Color Palette:** Modern, clean, and slightly futuristic. Primary: Dark background (e.g., `#121212` or a deep navy `#1A202C`). Accent: Vibrant but not overpowering color for interactive elements and highlights (e.g., a teal `#38B2AC` or a bright blue `#4299E1`). Secondary: Lighter grays for text and borders (e.g., `#A0AEC0`, `#E2E8F0`).
* **Typography:** Clean, readable sans-serif font. Primary: Inter or Poppins. Headings should be distinct but not overly large. Body text should be comfortable for reading.
* **Component Design:** Card-based design for model listings. Clear buttons with distinct states (default, hover, active, disabled). Progress bars for downloads. Minimalistic chat interface.
* **Responsiveness:** Primarily designed for desktop (1280px+ width). Mobile responsiveness will be considered for future iterations, but the initial focus is on desktop application experience via Electron.
* **Interactivity:** Subtle hover effects on cards and buttons. Smooth transitions for panel expansions or content changes. Clear loading indicators.
* **Accessibility:** Use semantic HTML, ensure sufficient color contrast, keyboard navigation support for interactive elements (using Headless UI will help significantly).
## 5. COMPONENT BREAKDOWN
* **`App.jsx`:** Main application wrapper. Sets up routing (if any), global styles, and theme provider. Renders `Sidebar` and `MainContent`. Manages global state initialization via Zustand.
* **`Sidebar.jsx`:** Persistent navigation menu. Contains links to different sections. Uses `Link` from `react-router-dom`. Receives `activeSection` state and `setActiveSection` function.
* Props: `activeSection`, `onNavigate`
* **`MainContent.jsx`:** Container for the content area. Switches between different views based on the `activeSection` state.
* Props: `activeSection`
* **`ModelCatalog.jsx`:** Displays the list of available AI models. Fetches (or uses mock) data. Includes `SearchBar` and `FilterControls`. Renders a grid of `ModelCard` components.
* State: `models`, `filteredModels`, `searchQuery`, `filters`
* **`SearchBar.jsx`:** Input field for searching models.
* Props: `value`, `onChange`
* **`FilterControls.jsx`:** Buttons/dropdowns for filtering models.
* Props: `filters`, `onFilterChange`
* **`ModelCard.jsx`:** Displays a single AI model's summary information in a card format.
* Props: `model` (object containing name, size, features, icon, etc.), `onClick` (to view details)
* **`ModelDetail.jsx`:** Displays detailed information about a selected model. Includes 'Download' button, specs, description.
* Props: `modelId`, `onDownload`
* **`DownloadProgress.jsx`:** Visual indicator for model download status (progress bar, percentage, status text).
* Props: `downloadState` (object with progress, status, eta)
* **`MyModels.jsx`:** Lists all locally downloaded models. Renders `MyModelCard` components.
* State: `localModels`
* **`MyModelCard.jsx`:** Represents a downloaded model in the 'My Models' list. Shows status, allows actions (Run, Stop, Delete).
* Props: `model`, `onAction`
* **`ChatInterface.jsx`:** The core interaction UI for a running model. Includes message input, display area for conversation, and potentially resource monitoring overlay.
* State: `messages`, `input`, `activeModel` (from global state), `resourceUsage`
* Props: `model` (selected model object)
* **`ResourceMonitor.jsx`:** Small overlay or panel showing CPU, RAM, VRAM usage.
* Props: `usage` (object with cpu, ram, vram)
* **`Settings.jsx`:** Application settings (e.g., download directory, theme preference).
## 6. DATA MODEL & STATE MANAGEMENT (Zustand Stores)
**`useModelStore.js`:** Manages the catalog of available models and the download/installation process.
```javascript
{
models: [], // Array of model objects from the catalog
downloadingModelId: null, // ID of the model currently being downloaded
downloadProgress: 0, // 0-100
downloadStatus: 'idle' | 'downloading' | 'paused' | 'completed' | 'error',
errorMessage: null,
fetchModels: async () => { /* logic to fetch model catalog */ },
downloadModel: async (modelId) => { /* logic to start download */ },
cancelDownload: () => { /* logic to cancel */ },
deleteModel: async (modelId) => { /* logic to delete local file */ },
}
```
**`useLocalModelsStore.js`:** Manages the user's collection of downloaded models.
```javascript
{
localModels: [], // Array of model objects that are downloaded
runningModelId: null, // ID of the model currently running
resourceUsage: { cpu: 0, ram: 0, vram: 0 }, // Real-time usage
startModel: async (modelId) => { /* logic to start local execution */ },
stopModel: async (modelId) => { /* logic to stop local execution */ },
deleteLocalModel: async (modelId) => { /* logic to remove from list & potentially delete file */ },
updateResourceUsage: (usage) => { /* updates the resourceUsage state */ },
}
```
**`useChatStore.js` (for `ChatInterface`):** Manages the state for a specific chat session.
```javascript
{
messages: [], // Array of message objects { sender: 'user'|'ai', text: '...' }
input: '', // Current user input text
addMessage: (message) => { /* adds message to array */ },
setInput: (text) => { /* updates input */ },
clearChat: () => { /* resets messages and input */ },
}
```
**Mock Data Format (`model` object):**
```json
{
"id": "llama3-8b-instruct-q4km",
"name": "Llama 3.1 8B Instruct",
"provider": "Meta",
"size": "4.1 GB",
"ctx": "128K",
"quantizations": ["Q2_K", "Q3_K_M", "Q4_K_M", "Q5_K_M", "Q6_K", "Q8_0", "F16"],
"features": ["chat", "reasoning"],
"releaseDate": "2024-07",
"architecture": "Dense",
"downloadUrl": "/path/to/models/llama3-8b-instruct-q4km.gguf", // Local path or URL
"icon": "/icons/llama.svg",
"description": "Meta's versatile 8B model with a great quality/speed ratio."
}
```
**Mock Data Format (`message` object):
```json
{
"id": "msg_12345",
"sender": "user", // or "ai"
"text": "What is the capital of France?",
"timestamp": "2023-10-27T10:30:00Z"
}
```
## 7. ANIMATIONS & INTERACTIONS
* **Hover Effects:** Subtle background color change or slight scaling on `ModelCard` and buttons when hovered.
* **Transitions:** Smooth slide-in/fade-in for new models appearing in the catalog. Smooth transition for the `ChatInterface` appearing/disappearing. Panel expansions (like settings or model details) should animate.
* **Loading States:** Skeletons or spinners for `ModelCatalog` while data is loading. Progress bars for downloads. A distinct loading indicator within the `ChatInterface` while waiting for AI response.
* **Micro-interactions:** Button press feedback. Smooth scrolling. Subtle animations on resource usage meters.
## 8. EDGE CASES & ERROR HANDLING
* **Empty States:** Display friendly messages and clear calls to action when the model catalog is empty, no models are downloaded, or the chat history is empty.
* **Error Management:** Gracefully handle network errors during catalog fetching. Display clear error messages for download failures (e.g., insufficient disk space, network issues, corrupted file). Provide informative messages for model execution errors.
* **Validation:** Validate user inputs (e.g., search queries, chat input if length limits apply). Ensure download paths are valid and writable.
* **Resource Constraints:** Inform the user if their system doesn't meet the minimum requirements for downloading or running certain models. Warn if download is likely to fail due to low disk space.
* **Interrupted Downloads:** Allow resuming interrupted downloads if the server supports it (or provide an option to retry).
* **Accessibility (a11y):** Ensure all interactive elements are focusable and operable via keyboard. Use ARIA attributes where necessary. Maintain good color contrast. Provide alt text for images/icons.
* **Model Compatibility:** Clearly indicate which models are compatible with the user's system (e.g., CPU vs GPU requirements). Provide guidance on choosing appropriate quantization levels.
## 9. SAMPLE DATA
* **Model Catalog (Example Subset):**
```json
[
{
"id": "llama3-8b-instruct-q4km",
"name": "Llama 3.1 8B Instruct",
"provider": "Meta",
"size": "4.1 GB",
"ctx": "128K",
"quantizations": ["Q4_K_M", "Q8_0"],
"features": ["chat", "reasoning"],
"icon": "/icons/llama.svg",
"description": "Meta's versatile 8B model with a great quality/speed ratio."
},
{
"id": "mistral-7b-instruct-v0.2-q5k",
"name": "Mistral 7B Instruct v0.2",
"provider": "Mistral AI",
"size": "5.5 GB",
"ctx": "32K",
"quantizations": ["Q5_K_M", "Q6_K"],
"features": ["chat", "code"],
"icon": "/icons/mistral.svg",
"description": "Optimized instruction-following model from Mistral AI."
},
{
"id": "phi-3-mini-4k-instruct-q4k",
"name": "Phi-3 Mini 4K Instruct",
"provider": "Microsoft",
"size": "2.8 GB",
"ctx": "4K",
"quantizations": ["Q4_K_M"],
"features": ["reasoning", "chat"],
"icon": "/icons/phi.svg",
"description": "Microsoft's compact yet powerful reasoning model."
}
]
```
* **Local Models State (Example):**
```json
[
{
"id": "llama3-8b-instruct-q4km",
"name": "Llama 3.1 8B Instruct",
"status": "running", // 'downloaded', 'downloading', 'error'
"progress": 100,
"localPath": "/Users/user/models/llama3-8b-instruct-q4km.gguf"
}
]
```
* **Chat Messages (Example):**
```json
[
{
"id": "msg_abc",
"sender": "user",
"text": "Hello, who are you?",
"timestamp": "2024-07-27T10:00:00Z"
},
{
"id": "msg_def",
"sender": "ai",
"text": "I am a local AI model, ready to assist you.",
"timestamp": "2024-07-27T10:00:05Z"
}
]
```
## 10. DEPLOYMENT NOTES
* **Build Process:** Use Vite (`npm run build`) for optimized frontend builds. For Electron, use `electron-builder` or similar tool to package the application for different platforms.
* **Environment Variables:** Use `.env` files for managing settings like the default download directory, API keys (if any are needed for model catalog fetching), or Electron-specific configurations.
* **Performance Optimizations:** Code splitting with React.lazy and Suspense for large components. Optimize image/icon loading. Memoization (React.memo, useMemo, useCallback) where appropriate. Efficient state updates using Zustand.
* **Cross-Platform Compatibility:** Ensure Electron builds are tested on Windows, macOS, and Linux. Handle platform-specific file paths and permissions carefully.
* **Model Management Logic:** The core logic for downloading, verifying, and potentially running models needs to be robust. Consider using a background process or worker threads (within Electron) to avoid blocking the UI during I/O intensive operations like downloads.
* **Updates:** Plan for how the application itself will be updated, and how model catalog information will be refreshed.