feat(onboarding): implement dynamic default models based on device RAM (#228)

## PR Objective
This Pull Request introduces dynamic default model suggestions on the
onboarding screen based on the device's available RAM.

Resolves #222.

By tailoring the initial model suggestions to the hardware capabilities,
we prevent out-of-memory crashes on low-end devices while ensuring that
high-end device users get the most capable (and multimodal) models right
out of the box.

## What changed?

### New Features & Logic
* **Dynamic Thresholds:** Replaced the static `startingModels` array
with a new dynamic function that evaluates the device's RAM (in GB).
* **Categorized Model Tiers:** * **Low-end (< 4 GB RAM):** Suggests
lightweight models (e.g., `Qwen 3 - 0.6B`, `LFM 2.5 VL - 450M`) that fit
comfortably in limited memory.
* **Mid-range (4 - 6 GB RAM):** Suggests balanced models (e.g., `LLaMA
3.2 - 1B - SpinQuant`, `Qwen 3 - 1.7B`).
* **High-end (> 6 GB RAM):** Suggests the most powerful and multimodal
models (e.g., `Gemma 4 VL - 2B`, `Qwen 2.5 - 3B`).
* **Onboarding Integration:** Connected the RAM-fetching utility to the
Onboarding component to seamlessly inject these dynamic recommendations
during the initial setup.

### Tests
* Added unit tests to verify that the correct array of models is
returned for each specific RAM threshold (Low, Mid, and High-end).

---------

Co-authored-by: Norbert Klockiewicz <Nklockiewicz12@gmail.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: 3 people

__tests__/defaultModels.test.ts

@@ -0,0 +1,38 @@
+import { getStartingModels } from '../constants/default-models';
+
+describe('getStartingModels', () => {
+  it('returns low-end model suggestions below 4 GB RAM', () => {
+    expect(getStartingModels(3.99)).toEqual([
+      'Qwen 3 - 0.6B',
+      'LFM 2.5 VL - 450M',
+      'LFM 2.5 - 1.2B',
+    ]);
+  });
+
+  it('returns mid-range model suggestions from 4 GB to 6 GB RAM', () => {
+    expect(getStartingModels(4)).toEqual([
+      'Qwen 3 - 1.7B',
+      'LFM 2.5 - 1.2B',
+      'LFM 2.5 VL - 1.6B',
+    ]);
+    expect(getStartingModels(6)).toEqual([
+      'Qwen 3 - 1.7B',
+      'LFM 2.5 - 1.2B',
+      'LFM 2.5 VL - 1.6B',
+    ]);
+  });
+
+  it('returns high-end model suggestions above 6 GB RAM', () => {
+    expect(getStartingModels(6.01)).toEqual([
+      'Gemma 4 - 2B',
+      'Gemma 4 VL - 2B',
+      'Qwen 3 - 1.7B',
+    ]);
+  });
+
+  it('falls back to low-end suggestions when RAM detection fails or is zero', () => {
+    const lowEnd = ['Qwen 3 - 0.6B', 'LFM 2.5 VL - 450M', 'LFM 2.5 - 1.2B'];
+    expect(getStartingModels(0)).toEqual(lowEnd);
+    expect(getStartingModels(-1)).toEqual(lowEnd);
+  });
+});

__tests__/modelRepository.test.ts

@@ -1,14 +1,17 @@
 // __tests__/modelRepository.test.ts
-import { getAllModels, addModel } from '../database/modelRepository';
+import { type SQLiteDatabase } from 'expo-sqlite';
+import { getAllModels, getModelsByNames } from '../database/modelRepository';
 
 jest.mock('expo-sqlite', () => {
   const stableDb = {};
   return { useSQLiteContext: jest.fn(() => stableDb) };
 });
 
+type ModelReader = Pick<SQLiteDatabase, 'getAllAsync'>;
+
 describe('vision flag', () => {
   it('maps vision INTEGER 1 to boolean true from DB row', async () => {
-    const mockDb = {
+    const mockDb: ModelReader = {
       getAllAsync: jest.fn().mockResolvedValue([
         {
           id: 1,
@@ -26,14 +29,14 @@ describe('vision flag', () => {
           modelSize: null,
         },
       ]),
-    } as any;
+    };
 
     const models = await getAllModels(mockDb);
     expect(models[0].vision).toBe(true);
   });
 
   it('maps vision INTEGER 0 to boolean false from DB row', async () => {
-    const mockDb = {
+    const mockDb: ModelReader = {
       getAllAsync: jest.fn().mockResolvedValue([
         {
           id: 1,
@@ -51,7 +54,7 @@ describe('vision flag', () => {
           modelSize: null,
         },
       ]),
-    } as any;
+    };
 
     const models = await getAllModels(mockDb);
     expect(models[0].vision).toBe(false);
@@ -60,7 +63,7 @@ describe('vision flag', () => {
 
 describe('systemPrompt field', () => {
   it('maps systemPrompt string from DB row', async () => {
-    const mockDb = {
+    const mockDb: ModelReader = {
       getAllAsync: jest.fn().mockResolvedValue([
         {
           id: 1,
@@ -79,14 +82,14 @@ describe('systemPrompt field', () => {
           systemPrompt: 'Polish prompt',
         },
       ]),
-    } as any;
+    };
 
     const models = await getAllModels(mockDb);
     expect(models[0].systemPrompt).toBe('Polish prompt');
   });
 
   it('maps null systemPrompt from DB row', async () => {
-    const mockDb = {
+    const mockDb: ModelReader = {
       getAllAsync: jest.fn().mockResolvedValue([
         {
           id: 1,
@@ -105,9 +108,62 @@ describe('systemPrompt field', () => {
           systemPrompt: null,
         },
       ]),
-    } as any;
+    };
 
     const models = await getAllModels(mockDb);
     expect(models[0].systemPrompt).toBeNull();
   });
 });
+
+describe('getModelsByNames', () => {
+  it('returns models in the requested order', async () => {
+    const mockDb: ModelReader = {
+      getAllAsync: jest.fn().mockResolvedValue([
+        {
+          id: 2,
+          modelName: 'Qwen 3 - 1.7B',
+          source: 'remote',
+          isDownloaded: 0,
+          modelPath: '',
+          tokenizerPath: '',
+          tokenizerConfigPath: '',
+          featured: 1,
+          experimental: 0,
+          thinking: 1,
+          vision: 0,
+          labels: null,
+          parameters: 2.03,
+          modelSize: 2.16,
+          systemPrompt: null,
+        },
+        {
+          id: 1,
+          modelName: 'LFM 2.5 - 1.2B',
+          source: 'remote',
+          isDownloaded: 0,
+          modelPath: '',
+          tokenizerPath: '',
+          tokenizerConfigPath: '',
+          featured: 1,
+          experimental: 0,
+          thinking: 0,
+          vision: 0,
+          labels: null,
+          parameters: 1.2,
+          modelSize: 1.14,
+          systemPrompt: null,
+        },
+      ]),
+    };
+
+    const models = await getModelsByNames(mockDb, [
+      'LFM 2.5 - 1.2B',
+      'Qwen 3 - 1.7B',
+    ]);
+
+    expect(models.map((model) => model.modelName)).toEqual([
+      'LFM 2.5 - 1.2B',
+      'Qwen 3 - 1.7B',
+    ]);
+  });
+});

app/(modals)/select-starting-model.tsx

@@ -11,8 +11,10 @@ import { getNextChatId } from '../../database/chatRepository';
 import { useChatStore } from '../../store/chatStore';
 import { useLLMStore } from '../../store/llmStore';
 import { useSQLiteContext } from 'expo-sqlite';
-import { getStartingModels, Model } from '../../database/modelRepository';
+import { getModelsByNames, Model } from '../../database/modelRepository';
 import { Theme } from '../../styles/colors';
+import { getStartingModels } from '../../constants/default-models';
+import { getDeviceMemoryGB } from '../../utils/modelCompatibility';
 
 function SelectStartingModelScreen() {
   const router = useRouter();
@@ -24,10 +26,16 @@ function SelectStartingModelScreen() {
   const { downloadedModels } = useModelStore();
   const [selectedModel, setSelectedModel] = useState<Model | null>(null);
   const [startingModels, setStartingModels] = useState<Model[]>([]);
+  const suggestedStartingModelNames = useMemo(
+    () => getStartingModels(getDeviceMemoryGB()),
+    []
+  );
 
   useEffect(() => {
-    getStartingModels(db).then((models) => setStartingModels(models));
-  }, [db]);
+    getModelsByNames(db, suggestedStartingModelNames).then((models) =>
+      setStartingModels(models)
+    );
+  }, [db, suggestedStartingModelNames]);
 
   useEffect(() => {
     if (downloadedModels.length > 0) setSelectedModel(downloadedModels[0]);
@@ -73,8 +81,8 @@ function SelectStartingModelScreen() {
                 model={model}
                 onPress={
                   downloadedModels.find((m) => m.id === model.id)
-                    ? (model) => {
-                        setSelectedModel(model);
+                    ? (pressedModel) => {
+                        setSelectedModel(pressedModel);
                       }
                     : () => {}
                 }

constants/default-models.ts

@@ -17,11 +17,17 @@ import {
   GEMMA4_E2B_MM,
 } from 'react-native-executorch';
 
-export const startingModels = [
-  'LFM 2.5 - 1.2B',
-  'Gemma 4 VL - 2B',
-  'Qwen 3 - 1.7B',
-];
+export const getStartingModels = (deviceRamInGB: number): string[] => {
+  if (deviceRamInGB < 4) {
+    return ['Qwen 3 - 0.6B', 'LFM 2.5 VL - 450M', 'LFM 2.5 - 1.2B'];
+  }
+
+  if (deviceRamInGB <= 6) {
+    return ['Qwen 3 - 1.7B', 'LFM 2.5 - 1.2B', 'LFM 2.5 VL - 1.6B'];
+  }
+
+  return ['Gemma 4 - 2B', 'Gemma 4 VL - 2B', 'Qwen 3 - 1.7B'];
+};
 
 const RNE_MODELS = [
   QWEN3_0_6B_QUANTIZED,

database/modelRepository.ts

@@ -1,5 +1,5 @@
 import { type SQLiteDatabase } from 'expo-sqlite';
-import { DEFAULT_MODELS, startingModels } from '../constants/default-models';
+import { DEFAULT_MODELS } from '../constants/default-models';
 
 export type Model = {
   id: number;
@@ -167,11 +167,23 @@ export const updateModel = async (
   );
 };
 
-export const getStartingModels = async (db: SQLiteDatabase) => {
-  const placeholders = startingModels.map(() => '?').join(', ');
+export const getModelsByNames = async (
+  db: SQLiteDatabase,
+  modelNames: string[]
+) => {
+  if (modelNames.length === 0) {
+    return [];
+  }
+
+  const placeholders = modelNames.map(() => '?').join(', ');
   const rawModels = await db.getAllAsync<RawModel>(
     `SELECT * FROM models WHERE modelName IN (${placeholders})`,
-    startingModels
+    modelNames
   );
-  return rawModels.map(hydrateModel);
+  return rawModels
+    .map(hydrateModel)
+    .sort(
+      (a, b) =>
+        modelNames.indexOf(a.modelName) - modelNames.indexOf(b.modelName)
+    );
 };